Swagger

此笔记基于Swagger3.0记录，与之前版本略有不同

• API框架
• Restful Api 文档在线自动生成工具，api文档与api接口同步更新
• 直接运行，无需第三方工具，在线测试
• 支持多种语言：Java、php…

Springboot快速接入

swagger 需要两个jar包

• springfox-swagger-ui
• springfox-swagge2

1. maven 仓库搜索对应的jar包https://mvnrepository.com/search?q=springfox-swagger
   
   讯享网

   

2. 导入上面搜索到的的两个jar包依赖
   3.0版本导入此依赖即可

   <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency> 

   
   讯享网
3. 配置类
   xxxApplication.java，在启动类开启api注解

   讯享网@SpringBootApplication @EnableOpenApi //开启api注解 public class SwaggerDemoApplication { 
         public static void main(String[] args) { 
         SpringApplication.run(SwaggerDemoApplication.class, args); } } 

4. controller测试
   写一个接口测试，这里是GET模式

   @RestController public class HelloController { 
         @RequestMapping(value = "/hello",method = RequestMethod.GET) public String hello() { 
         return "hello"; } } 

5. swagger后台页面
   3.0地址：http://localhost:8080/swagger-ui/index.html

   

   可以看到接口已正常显示文档，快速接入完成。

Swagger启动失败的问题

报空指针异常

讯享网...... org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException ...... Caused by: java.lang.NullPointerException: null ...... 

这是因为springboot版本太高

解决方式1：把springboot版本降至2.5.6以下

解决方式2：在application.yml加入配置

spring: mvc: pathmatch: matching-strategy: ant_path_matcher 

Swagger3.0后台地址

http://localhost:8080/swagger-ui/index.html

Swager2.x后台地址：

http://localhost:8080/swagger-ui.html

Swagger3常用注解

1.@Api

tags：描述该类的作用

2.@ApiOperation

3.@ApiImplicitParams

说明：用在请求的方法上，表示一组参数说明

常用属性：

@ApiImplicitParam
说明：定义参数各项信息
常用属性：
name：参数名称
value：参数说明
required：是否必传，值为Boolean类型
paramType：参数放在哪个地方，常用值为：query（放在请求参数中，@RequestParam获取参数）、header（放在请求头中，@RequestHeader获取参数）、path（用于restful接口，@PathVariable获取参数）
dataType：参数类型，默认String
defaultValue：参数的默认值

4.@ApiResponses

@ApiResponse
说明：一般用于表达一个错误的响应信息
常用属性：
code：响应码
message：响应信息
response：抛出异常的类

5.@ApiModel

说明：用于响应类上，描述响应的数据对象

6.@ApiModelProperty

name：参数名称
value：参数说明
required：是否必传，值为Boolean类型
dataType：参数类型，默认String

示例

@Api()、@ApiOperation

@ApiImplicitParams

@ApiResponses、@ApiModel、@ApiModelProperty

controller

pojo

api文档

Swagger3配置信息

API文档信息

配置文档信息通过重写ApiInfo以及Docket来实现

讯享网@Configuration public class SwaggerConfig { 
    @Bean public Docket createDocket() { 
    //OAS_30 指定swagger3版本，可以点进源码查看信息 //apiInfo 使用自建api信息模板 return new Docket(DocumentationType.OAS_30).apiInfo(createApiInfo()); } @Bean public ApiInfo createApiInfo() { 
    return new ApiInfo( "title标题", "desc内容", //版本 "0.0.1", //团队url "urn:tos", //作者信息，团队老大，联系人 new Contact("xzlyf","http://localhost:8080/","邮箱"), //开源信息 "Apache2.0", "http://www.apache.org/licenses/LICENSE-2.0", //供应商，默认空 new ArrayList<>()); } } 

对应效果

Swagger的开关

一般情况下只有开发环境下才会用到swagger，正式环境需要关闭swagger。一个是安全问题，另一个是swagger会影响性能。

也是基于修改Docket来实现，所有的swagger配置都与docket有关

@Bean public Docket createDocket() { 
    //OAS_30 指定swagger3版本，可以点进源码查看信息 //apiInfo 使用自建api信息模板 return new Docket(DocumentationType.OAS_30) .apiInfo(createApiInfo()) .enable(false);//false表示关闭swagger后台页面 } 

刷新浏览器后发现不可访问后台页面了

API接口过滤

默认swagger扫描所有api，通过配置可以扫描指定的api

也是基于修改Docket来实现

讯享网@Bean public Docket createDocket() { 
    //OAS_30 指定swagger3版本，可以点进源码查看信息 //apiInfo 使用自建api信息模板 return new Docket(DocumentationType.OAS_30) .apiInfo(createApiInfo())//api文档信息 .enable(true)//swagger的开关 //api接口过滤 .select()//api 接口过滤 开始，符合过滤规则的才会在后台页面显示 //basePackage() 指定过滤的包 //any() 过滤全部 //none() 拒绝所有 //withClassAnnotation() 过滤类上的注解，例如@RestController这就是类上注解，方法上不可使用此注解 //withMethodAnnotation() 过滤方法上的注解，例如@GetMapping就是方法上注解，不可在类上使用，只能在方法上使用 .apis(RequestHandlerSelectors.basePackage("com.xz.swagger.demo.controller")) //仅在localhost:8080/test/ 路径下的接口能够过滤到，正则表达式 .paths(PathSelectors.ant("/test/")) .build();//api 接口过滤 结束，链式调用通过build()完成构建 } 

一般使用basePacker()指定包名下的过滤即可 .apis() basePackage() 指定过滤的包 any() 过滤全部 none() 拒绝所有 withClassAnnotation() 过滤类上的注解，例如@RestController这就是类上注解，方法上不可使用此注解 withMethodAnnotation() 过滤方法上的注解，例如@GetMapping就是方法上注解，不可在类上使用，只能在方法上使用 //根据接口路径进行过滤 .paths() PathSelectors.ant("接口路径正则") 

通过select()的链式调用来时实现，通过build()来完成构建

分组管理

设置单个分组

多分组设置

通过设置多个docket来完成，每个docket相当与一个api文档

而且每个docket可以对应不同的ApiInfo信息