SpringBoot 整合 Swagger2
我写的Github 地址 SpringBoot+Swagger2 Github
我在使用的时候遇到一点很神奇的问题,SpringBoot 版本为 2.1.6.RELEASE的时候,就会报错,换到2.1.4.RELEASE的时候就正常了,很神奇。回头再研究下
加入依赖
1 | <dependency> |
1 | @Configuration |
可以访问 http://localhost:8080/swagger-ui.html
(来自网上的复制粘贴,记录下方便之后查询)
springfox的标签
@Api:修饰整个类,描述Controller的作用
@ApiOperation:描述一个类的一个方法,或者说一个接口
@ApiImplicitParams:多个请求参数
@ApiImplicitParam:一个请求参数
@ApiResponses:HTTP响应整体描述
@ApiResponse:HTTP响应其中1个描述
@ApiModel:用对象来接收参数
@ApiModelProperty:用对象接收参数时,描述对象的一个字段
@ApiIgnore:使用该注解忽略这个API
类和方法的描述
@Api修饰整个类,描述Controller的作用
@ApiOperation 贴在方法上,描述一个方法的作用
1) @Api注解的使用:贴在类上,主要用下面的这几个属性
1) value:该controller简短的标题
2) description:详细介绍
3) producer:说明该controller是使用什么显示层格式的
4) protocols:使用什么协议
2) @ApiOperation注解的使用:贴在方法上,主要用下面的这几个属性
1) value:该方法简短的变态
2) note:详细介绍
3)code:正常情况下返回的状态码是多少
4)httpMethod:使用什么http方法
5) response:响应什么对象,这里写的是响应的对象的字节码
参数的描述
贴在参数上
@ApiImplicitParams 多个请求参数
@ApiImplicitParam 一个请求参数
@ApiParam 单个参数描述
1) name:参数名
2) value:参数名对应的值
3) dataType:参数的类型
4) require:该参数是否必填
5) paramType:该参数的来源类型,它的值有如下:
query:该参数从地址栏问号后面的参数获取
form:该参数从form表单中获取
path:该参数从URL地址上获取
body:该参数从请求体中获取
header:该参数从请求头获取
响应的描述
@ApiResponses:HTTP响应整体的描述
@ApiResponse:HTTP响应中某一种响应的描述
用在@ApiResponses中,一般用于表达一个错误的响应信息(200相应不写在这里面)
code:数字,例如400
message:信息,例如”请求参数没填好”
response:抛出的异常类
对象模型描述
@ApiModel/@ApiModelProperty
@ApiModel:描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用
@ApiImplicitParam注解进行描述的时候)
@ApiModelProperty:描述一个model的属性
忽略接口API
@ApiIgnore 贴了该注解的api 会被忽略,不生成接口文档
两种不生成api的方式
1) @ApiIgnore:可以贴在类和方法上
2) 在swagger配置类上的select()方法上调用apis(),apis方法需要传入一个selector。可以使用RequestHandlerSelector内置的selector