Swagger快速入门教程笔记

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.springfoxgroupId>
       <artifactId>springfox-boot-starterartifactId>
       <version>3.0.0version>
   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

说明：用在请求的方法上，说明方法的作用和备注
常用属性：

value：描述方法的作用
notes：备注说明

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

说明：用在JavaBean属性上，描述响应类的属性或请求类的属性
常用属性：

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信息