Spring Boot（9）之 Swagger 接口文档生成器

1、添加依赖

spring4all工具源码

    <dependency>
        <groupId>com.spring4all</groupId>
        <artifactId>swagger-spring-boot-starter</artifactId>
        <version>1.9.1.RELEASE</version>
    </dependency>

2、入口添加注释

import com.spring4all.swagger.EnableSwagger2Doc;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@EnableSwagger2Doc // 启动文档
@SpringBootApplication
public class OsFastStableApplication {

	public static void main(String[] args) {
		SpringApplication.run(OsFastStableApplication.class, args);
	}

}

3、常用注解

3.1、@Api()：类

用在请求的类上，表示对类的说明，也代表了这个类是swagger2的资源

参数	说明	备注
tags	说明该类的作用（标签），参数是个数组，可以填多个
value	该参数没什么意义，在UI界面上不显示，所以不用配置
description	类的描述

3.2、@ApiOperation()：方法

用于方法，表示一个http请求访问该方法的操作

参数	说明	备注
value	方法的用途和作用
notes	方法的注意事项和备注
tags	说明该方法的作用，参数是个数组，可以填多个	格式：tags={“作用1”,“作用2”}

注意：在这里建议不使用 tags 这个参数，会使界面看上去有点乱，前两个常用

3.3、@ApiModel()：实体类

用于响应实体类上，用于说明实体作用

参数	说明	备注
description	描述实体的作用

3.4、@ApiModelProperty()：实体类属性

用在属性上，描述实体类的属性

参数	说明	备注
name	参数的变量名	name=“name”
value	描述参数的意义	value=“用户名”
required	参数是否必选	required=true

3.5、@ApiImplicitParams()：请求方法

用在请求的方法上，包含多@ApiImplicitParam

@ApiImplicitParams(value = {
            @ApiImplicitParam( ... ),
            @ApiImplicitParam( ... )
})

3.6、@ApiImplicitParam()：请求方法

用于方法，表示单独的请求参数

参数	说明	备注
name	参数的变量名
value	描述参数的意义
dataType	数据类型
paramType	表示参数放在哪里	· header 请求参数的获取：@RequestHeader · query 请求参数的获取：@RequestParam · path（用于restful接口） 请求参数的获取：@PathVariable · body（不常用） · form（不常用）
defaultValue	参数的默认值
required	表示参数是否必须传	required=true

3.7、@ApiParam()：方法参数

用于方法，参数，字段说明 表示对参数的要求和说明

• 注意：@ApiParam 与 @ApiImplicitParam 作用相同，但是 @ApiImplicitParam 的适用范围更广

参数	说明	备注
name	参数的变量名	name=“name”
value	描述参数的意义	value=“用户名”
defaultValue	参数默认值
required	参数是否必选	默认为false

    @ApiOperation("用户列表")
    @GetMapping("/users")
    public List<User> list(@ApiParam("查看第几页") @RequestParam int pageIndex,
                            @ApiParam("每页多少条") @RequestParam int pageSize) {
        List<User> result = new ArrayList<>();
        result.add(new User("aaa", 50, "北京", "aaa@ccc.com"));
        result.add(new User("bbb", 21, "广州", "aaa@ddd.com"));
        return result;
    }

3.8、@ApiResponses()：请求方法

用于请求的方法上，根据响应码表示不同响应

• 一个@ApiResponses包含多个@ApiResponse

@ApiResponses(value = {
        @ApiResponse(code = 200, message = "Success", response = Order.class),
        @ApiResponse(code = 405, message = "Error", response = Order.class)
})

3.9、@ApiResponse()：请求方法

用在请求的方法上，表示不同的响应

参数	说明	备注
code	表示响应码(int型)	可自定义
message	状态码对应的响应信息
response	返回响应	Class类型
...	其他参数不常用	可以自行查看源码

3.10、@ApiIgnore()：类、方法

用于类或者方法上，不被显示在页面上

3.11、@Profile({“dev”, “test”})：配置类

用于配置类上，表示只对开发和测试环境有用

4、配置详情

4.1、其他

命令	说明	案例
spring.application.name	spring 应用程序名称	swagger-demo
logging.level.org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping		trace

4.2、Swagger Enable/Disable

命令	说明	案例
springfox.documentation.enabled		TRUE

4.3、Swagger Switch

命令	说明	案例
swagger.enabled	是否启用swagger，默认：true

4.4、ApiInfo

命令	说明	案例
swagger.title	标题	spring-boot-starter-swagger
swagger.description	描述	Starter for swagger 2.x
swagger.version	版本	1.1.0.RELEASE
swagger.license	许可证	Apache License, Version 2.0
swagger.licenseUrl	许可证URL	https://www.apache.org/licenses/LICENSE-2.0.html
swagger.termsOfServiceUrl	服务条款URL	https://github.com/dyc87112/spring-boot-starter-swagger
swagger.contact.name	维护人	didi
swagger.contact.url	维护人URL	http://blog.didispace.com
swagger.contact.email	维护人email	dyc87112@qq.com
swagger.host	文档的host信息，默认：空	localhost:8081
…	…	…
swagger.base-package	swagger扫描的基础包，默认：全扫描	com.didispace
swagger.base-path	需要处理的基础URL规则，默认：/**	/**
swagger.exclude-path	需要排除的URL规则，默认：空	/error, /ops/**

4.5、忽略的参数配置

命令	说明	案例
swagger.ignored-parameter-types[0]		com.didispace.demo.User
swagger.ignored-parameter-types[1]		com.didispace.demo.Product

4.6、全局请求参数

命令	说明	案例
swagger.global-operation-parameters[0].name	参数名	access_token
swagger.global-operation-parameters[0].description	描述信息	user access token
swagger.global-operation-parameters[0].modelRef	指定参数类型	string
swagger.global-operation-parameters[0].parameterType	指定参数存放位置,可选header,query,path,body.form	header
swagger.global-operation-parameters[0].required	指定参数是否必传，true,false	TRUE

5、取消使用默认预定义的响应消息,并使用自定义响应消息

命令	说明	案例
swagger.apply-default-response-messages		FALSE
swagger.global-response-message.get[0].code		401
swagger.global-response-message.get[0].message		401get
swagger.global-response-message.get[1].code		500
swagger.global-response-message.get[1].message		500get
swagger.global-response-message.get[1].modelRef		ERROR
swagger.global-response-message.post[0].code		500
swagger.global-response-message.post[0].message		500post
swagger.global-response-message.post[0].modelRef		ERROR

5.1、UI功能配置

命令	说明	案例
swagger.ui-config.json-editor	json编辑器	FALSE
swagger.ui-config.show-request-headers	显示请求头	TRUE
swagger.ui-config.request-timeout	页面调试请求的超时时间	5000
swagger.ui-config.submit-methods	调试按钮的控制(try it out)，该参数值为提供调试按钮的HTTP请求类型，多个用,分割。	get,delete

5.2、分组配置

命令	说明	案例
swagger.docket.<name>.title	标题
swagger.docket.<name>.description	描述
swagger.docket.<name>.version	版本
swagger.docket.<name>.license	许可证
swagger.docket.<name>.licenseUrl	许可证URL
swagger.docket.<name>.termsOfServiceUrl	服务条款URL
swagger.docket.<name>.contact.name	维护人
swagger.docket.<name>.contact.url	维护人URL
swagger.docket.<name>.contact.email	维护人email
swagger.docket.<name>.base-package	swagger扫描的基础包，默认：全扫描
swagger.docket.<name>.base-path	需要处理的基础URL规则，默认：/**
swagger.docket.<name>.exclude-path	需要排除的URL规则，默认：空
swagger.docket.<name>.name	参数名
swagger.docket.<name>.modelRef	指定参数类型
swagger.docket.<name>.parameterType	指定参数存放位置,可选header,query,path,body.form
swagger.docket.<name>.required	TRUE
swagger.docket.<name>.globalOperationParameters[0].name	参数名
swagger.docket.<name>.globalOperationParameters[0].description	描述信息
swagger.docket.<name>.globalOperationParameters[0].modelRef	指定参数存放位置,可选header,query,path,body.form
swagger.docket.<name>.globalOperationParameters[0].parameterType	指定参数是否必传，true,false

6、Swagger UI 地址

http://localhost:8081/swagger-ui.html#/