1、添加依赖
<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#/