百度360必应搜狗淘宝本站头条
python判断字典是否为空crontab每周一执行aes和des区别安装指定版本npmadb pull
当前位置：网站首页 > IT知识 > 正文

Swagger3.0官方starte诞生了其它的都可以扔了

liuian 2025-02-26 12:45 13 浏览

  • 资料
  • swagger介绍
  • springfox介绍
  • SpringFox 3.0.0 发布
  • 整合使用
  • 一些常用注解说明
  • 示例
  • 参考

资料

  • swagger 官网：swagger.io
  • springfox 官网：springfox
  • springfox Github 仓库：springfox / springfox
  • springfox-demos Github 仓库：springfox / springfox-demos
  • springfox Maven 仓库：Home ? io.springfox

swagger介绍

对于 Rest API 来说很重要的一部分内容就是文档，Swagger 为我们提供了一套通过代码和注解自动生成文档的方法，这一点对于保证 API 文档的及时性将有很大的帮助。

Swagger 是一套基于 OpenAPI 规范（OpenAPI Specification，OAS）构建的开源工具，可以帮助我们设计、构建、记录以及使用 Rest API。

OAS本身是一个API规范，它用于描述一整套API接口，包括一个接口是哪种请求方式、哪些参数、哪些header等，都会被包括在这个文件中。它在设计的时候通常是YAML格式，这种格式书写起来比较方便，而在网络中传输时又会以json形式居多，因为json的通用性比较强。

Swagger 主要包含了以下三个部分：

  • Swagger Editor：基于浏览器的编辑器，我们可以使用它编写我们 OpenAPI 规范。
  • Swagger UI：它会将我们编写的 OpenAPI 规范呈现为交互式的 API 文档，后文我将使用浏览器来查看并且操作我们的 Rest API。
  • Swagger Codegen：它可以通过为 OpenAPI（以前称为 Swagger）规范定义的任何 API 生成服务器存根和客户端 SDK 来简化构建过程。

springfox介绍

由于Spring的流行，Marty Pitt编写了一个基于Spring的组件swagger-springmvc，用于将swagger集成到springmvc中来，而springfox则是从这个组件发展而来。

通常SpringBoot项目整合swagger需要用到两个依赖：springfox-swagger2和springfox-swagger-ui，用于自动生成swagger文档。

  • springfox-swagger2：这个组件的功能用于帮助我们自动生成描述API的json文件
  • springfox-swagger-ui：就是将描述API的json文件解析出来，用一种更友好的方式呈现出来。

SpringFox 3.0.0 发布

官方说明：

  • SpringFox 3.0.0 发布了，SpringFox 的前身是 swagger-springmvc，是一个开源的 API doc 框架，可以将 Controller 的方法以文档的形式展现。
  • 首先，非常感谢社区让我有动力参与这个项目。在这个版本中，在代码、注释、bug报告方面有一些非常惊人的贡献，看到人们在问题论坛上跳槽来解决问题，我感到很谦卑。它确实激励我克服“困难”，开始认真地工作。有什么更好的办法来摆脱科维德的忧郁！
  • 注意：这是一个突破性的变更版本，我们已经尽可能地保持与springfox早期版本的向后兼容性。在2.9之前被弃用的api已经被积极地删除，并且标记了将在不久的将来消失的新api。所以请注意这些，并报告任何遗漏的内容。

新特性：

  • Remove explicit dependencies on springfox-swagger2
  • Remove any @EnableSwagger2… annotations
  • Add the springfox-boot-starter dependency
  • Springfox 3.x removes dependencies on guava and other 3rd party libraries (not zero dep yet! depends on spring plugin and open api libraries for annotations and models) so if you used guava predicates/functions those will need to transition to java 8 function interfaces.

此版本的亮点：

  • Spring5，Webflux支持（仅支持请求映射，尚不支持功能端点）。
  • Spring Integration支持（非常感谢反馈）。
  • SpringBoot支持springfox Boot starter依赖性（零配置、自动配置支持）。
  • 具有自动完成功能的文档化配置属性。
  • 更好的规范兼容性与2.0。
  • 支持OpenApi 3.0.3。
  • 零依赖。几乎只需要spring-plugin，swagger-core ，现有的swagger2注释将继续工作并丰富openapi3.0规范。

兼容性说明：

  • 需要Java 8
  • 需要Spring5.x（未在早期版本中测试）
  • 需要SpringBoot 2.2+（未在早期版本中测试）

注意：

应用主类增加注解@EnableOpenApi，删除之前版本的SwaggerConfig.java。

启动项目，访问地址：http://localhost:8080/swagger-ui/index.html，注意2.x版本中访问的地址的为http://localhost:8080/swagger-ui.html

整合使用

Maven项目中引入springfox-boot-starter依赖：


????io.springfox
????springfox-boot-starter
????3.0.0

12345

application.yml配置

spring:
??application:
????name:?springfox-swagger
server:
??port:?8080

#?=====?自定义swagger配置?=====?#
swagger:
??enable:?true
??application-name:?${spring.application.name}
??application-version:?1.0
??application-description:?springfox?swagger?3.0整合Demo
??try-host:?http://localhost:${server.port}
12345678910111213

使用@EnableOpenApi注解，启用swagger配置

@EnableOpenApi
@Configuration
public?class?SwaggerConfiguration?{

}
12345

自定义swagger配置类SwaggerProperties

@Component
@ConfigurationProperties("swagger")
public?class?SwaggerProperties?{
????/**
?????*?是否开启swagger，生产环境一般关闭，所以这里定义一个变量
?????*/
????private?Boolean?enable;

????/**
?????*?项目应用名
?????*/
????private?String?applicationName;

????/**
?????*?项目版本信息
?????*/
????private?String?applicationVersion;

????/**
?????*?项目描述信息
?????*/
????private?String?applicationDescription;

????/**
?????*?接口调试地址
?????*/
????private?String?tryHost;

????public?Boolean?getEnable()?{
????????return?enable;
????}

????public?void?setEnable(Boolean?enable)?{
????????this.enable?=?enable;
????}

????public?String?getApplicationName()?{
????????return?applicationName;
????}

????public?void?setApplicationName(String?applicationName)?{
????????this.applicationName?=?applicationName;
????}

????public?String?getApplicationVersion()?{
????????return?applicationVersion;
????}

????public?void?setApplicationVersion(String?applicationVersion)?{
????????this.applicationVersion?=?applicationVersion;
????}

????public?String?getApplicationDescription()?{
????????return?applicationDescription;
????}

????public?void?setApplicationDescription(String?applicationDescription)?{
????????this.applicationDescription?=?applicationDescription;
????}

????public?String?getTryHost()?{
????????return?tryHost;
????}

????public?void?setTryHost(String?tryHost)?{
????????this.tryHost?=?tryHost;
????}
}
1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768

一个完整详细的springfox swagger配置示例：

import?io.swagger.models.auth.In;
import?org.apache.commons.lang3.reflect.FieldUtils;
import?org.springframework.boot.SpringBootVersion;
import?org.springframework.context.annotation.Bean;
import?org.springframework.context.annotation.Configuration;
import?org.springframework.util.ReflectionUtils;
import?org.springframework.web.servlet.config.annotation.InterceptorRegistration;
import?org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import?org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import?springfox.documentation.builders.ApiInfoBuilder;
import?springfox.documentation.builders.PathSelectors;
import?springfox.documentation.builders.RequestHandlerSelectors;
import?springfox.documentation.oas.annotations.EnableOpenApi;
import?springfox.documentation.service.*;
import?springfox.documentation.spi.DocumentationType;
import?springfox.documentation.spi.service.contexts.SecurityContext;
import?springfox.documentation.spring.web.plugins.Docket;

import?java.lang.reflect.Field;
import?java.util.*;

@EnableOpenApi
@Configuration
public?class?SwaggerConfiguration?implements?WebMvcConfigurer?{
????private?final?SwaggerProperties?swaggerProperties;

????public?SwaggerConfiguration(SwaggerProperties?swaggerProperties)?{
????????this.swaggerProperties?=?swaggerProperties;
????}

????@Bean
????public?Docket?createRestApi()?{
????????return?new?Docket(DocumentationType.OAS_30).pathMapping("/")

????????????????//?定义是否开启swagger，false为关闭，可以通过变量控制
????????????????.enable(swaggerProperties.getEnable())

????????????????//?将api的元信息设置为包含在json ResourceListing响应中。
????????????????.apiInfo(apiInfo())

????????????????//?接口调试地址
????????????????.host(swaggerProperties.getTryHost())

????????????????//?选择哪些接口作为swagger的doc发布
????????????????.select()
????????????????.apis(RequestHandlerSelectors.any())
????????????????.paths(PathSelectors.any())
????????????????.build()

????????????????//?支持的通讯协议集合
????????????????.protocols(newHashSet("https",?"http"))

????????????????//?授权信息设置，必要的header?token等认证信息
????????????????.securitySchemes(securitySchemes())

????????????????//?授权信息全局应用
????????????????.securityContexts(securityContexts());
????}

????/**
?????*?API?页面上半部分展示信息
?????*/
????private?ApiInfo?apiInfo()?{
????????return?new?ApiInfoBuilder().title(swaggerProperties.getApplicationName()?+?"?Api?Doc")
????????????????.description(swaggerProperties.getApplicationDescription())
????????????????.contact(new?Contact("lighter",?null,?"123456@gmail.com"))
????????????????.version("Application?Version:?"?+?swaggerProperties.getApplicationVersion()?+?",?Spring?Boot?Version:?"?+?SpringBootVersion.getVersion())
????????????????.build();
????}

????/**
?????*?设置授权信息
?????*/
????private?List?securitySchemes()?{
????????ApiKey?apiKey?=?new?ApiKey("BASE_TOKEN",?"token",?In.HEADER.toValue());
????????return?Collections.singletonList(apiKey);
????}

????/**
?????*?授权信息全局应用
?????*/
????private?List?securityContexts()?{
????????return?Collections.singletonList(
????????????????SecurityContext.builder()
????????????????????????.securityReferences(Collections.singletonList(new?SecurityReference("BASE_TOKEN",?new?AuthorizationScope[]{new?AuthorizationScope("global",?"")})))
????????????????????????.build()
????????);
????}

????@SafeVarargs
????private?final??Set?newHashSet(T...?ts)?{
????????if?(ts.length?>?0)?{
????????????return?new?LinkedHashSet<>(Arrays.asList(ts));
????????}
????????return?null;
????}

????/**
?????*?通用拦截器排除swagger设置，所有拦截器都会自动加swagger相关的资源排除信息
?????*/
????@SuppressWarnings("unchecked")
????@Override
????public?void?addInterceptors(InterceptorRegistry?registry)?{
????????try?{
????????????Field?registrationsField?=?FieldUtils.getField(InterceptorRegistry.class,?"registrations",?true);
????????????List?registrations?=?(List)?ReflectionUtils.getField(registrationsField,?registry);
????????????if?(registrations?!=?null)?{
????????????????for?(InterceptorRegistration?interceptorRegistration?:?registrations)?{
????????????????????interceptorRegistration
????????????????????????????.excludePathPatterns("/swagger**/**")
????????????????????????????.excludePathPatterns("/webjars/**")
????????????????????????????.excludePathPatterns("/v3/**")
????????????????????????????.excludePathPatterns("/doc.html");
????????????????}
????????????}
????????}?catch?(Exception?e)?{
????????????e.printStackTrace();
????????}
????}

}
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121

一些常用注解说明

  • @Api：用在controller类，描述API接口
  • @ApiOperation：描述接口方法
  • @ApiModel：描述对象
  • @ApiModelProperty：描述对象属性
  • @ApiImplicitParams：描述接口参数
  • @ApiResponses：描述接口响应
  • @ApiIgnore：忽略接口方法

示例

项目Demo：springfox-swagger

效果图：

相关推荐

2023年最新微信小程序抓包教程（微信小程序 抓包）

声明：本公众号大部分文章来自作者日常学习笔记，部分文章经作者授权及其他公众号白名单转载。未经授权严禁转载。如需转载，请联系开百。请不要利用文章中的相关技术从事非法测试。由此产生的任何不良后果与文...

测试人员必看的软件测试面试文档（软件测试面试怎么说）

前言又到了毕业季，我们将会迎来许多需要面试的小伙伴，在这里呢笔者给从事软件测试的小伙伴准备了一份顶级的面试文档。1、什么是bug?bug由哪些字段(要素)组成?1)将在电脑系统或程序中，隐藏着的...

复活，视频号一键下载，有手就会，长期更新(2023-12-21)

视频号下载的话题，也算是流量密码了。但也是比较麻烦的问题，频频失效不说，使用方法也难以入手。今天，奶酪就来讲讲视频号下载的新方案，更关键的是，它们有手就会有用，最后一个方法万能。实测2023-12-...

新款HTTP代理抓包工具Proxyman(界面美观、功能强大)

不论是普通的前后端开发人员，还是做爬虫、逆向的爬虫工程师和安全逆向工程，必不可少会使用的一种工具就是HTTP抓包工具。说到抓包工具，脱口而出的肯定是浏览器F12开发者调试界面、Charles(青花瓷)...

使用Charles工具对手机进行HTTPS抓包

本次用到的工具：Charles、雷电模拟器。比较常用的抓包工具有fiddler和Charles，今天讲Charles如何对手机端的HTTS包进行抓包。fiddler抓包工具不做讲解，网上有很多fidd...

苹果手机下载 TikTok 旧版本安装包教程

目前苹果手机能在国内免拔卡使用的TikTok版本只有21.1.0版本，而AppStore是高于21.1.0版本，本次教程就是解决如何下载TikTok旧版本安装包。前期准备准备美区...

【0基础学爬虫】爬虫基础之抓包工具的使用

大数据时代，各行各业对数据采集的需求日益增多，网络爬虫的运用也更为广泛，越来越多的人开始学习网络爬虫这项技术，K哥爬虫此前已经推出不少爬虫进阶、逆向相关文章，为实现从易到难全方位覆盖，特设【0基础学爬...

防止应用调试分析IP被扫描加固实战教程

防止应用调试分析IP被扫描加固实战教程一、概述在当今数字化时代，应用程序的安全性已成为开发者关注的焦点。特别是在应用调试过程中，保护应用的网络安全显得尤为重要。为了防止应用调试过程中IP被扫描和潜在的...

一文了解 Telerik Test Studio 测试神器

1.简介TelerikTestStudio（以下称TestStudio）是一个易于使用的自动化测试工具，可用于Web、WPF应用的界面功能测试，也可以用于API测试，以及负载和性能测试。Te...

HLS实战之Wireshark抓包分析（wireshark抓包总结）

0.引言Wireshark（前称Ethereal）是一个网络封包分析软件。网络封包分析软件的功能是撷取网络封包，并尽可能显示出最为详细的网络封包资料。Wireshark使用WinPCAP作为接口，直接...

信息安全之HTTPS协议详解(加密方式、证书原理、中间人攻击 )

HTTPS协议详解（加密方式、证书原理、中间人攻击）HTTPS协议的加密方式有哪些？HTTPS证书的原理是什么？如何防止中间人攻击？一：HTTPS基本介绍：1.HTTPS是什么：HTTPS也是一个...

Fiddler 怎么抓取手机APP:抖音、小程序、小红书数据接口

使用Fiddler抓取移动应用程序（APP）的数据接口需要进行以下步骤：首先，确保手机与计算机连接在同一网络下。在计算机上安装Fiddler工具，并打开它。将手机的代理设置为Fiddler代理。具体方...

python爬虫教程:教你通过 Fiddler 进行手机抓包

今天要说说怎么在我们的手机抓包有时候我们想对请求的数据或者响应的数据进行篡改怎么做呢？我们经常在用的手机手机里面的数据怎么对它抓包呢？那么...接下来就是学习python的正确姿势我们要用到一款强...

Fiddler入门教程全家桶，建议收藏

学习Fiddler工具之前，我们先了解一下Fiddler工具的特点，Fiddler能做什么？如何使用Fidder捕获数据包、修改请求、模拟客户端向服务端发送请求、实施越权的安全性测试等相关知识。本章节...

fiddler如何抓取https请求实现手机抓包(100%成功解决)

一、HTTP协议和HTTPS协议。(1)HTTPS协议=HTTP协议+SSL协议，默认端口：443(2)HTTP协议（HyperTextTransferProtocol）：超文本传输协议。默认...

一周热门
最近发表
标签列表