在spring-boot中使用Swagger
配置
1.需要依赖两个包:
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${springfox-version}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${springfox-version}</version>
</dependency>
第一个是API获取的包,第二是官方给出的一个ui界面。这个界面可以自定义,默认是官方的,对于安全问题,以及ui路由设置需要着重思考。
2.swagger的configuration
需要特别注意的是swagger scan base package,这是扫描注解的配置,即你的API接口位置。
当然,scan package 也可以换成别的条件,比如:
3.在API上做一些声明
4.设定访问API doc的路由
在配置文件中,application.yml中声明:
springfox.documentation.swagger.v2.path: /api-docs
这个path就是json的访问request mapping.可以自定义,防止与自身代码冲突。
API doc的显示路由是:http://localhost:8080/swagger-ui.html
如果项目是一个webservice,通常设定home / 指向这里:
5.新建实体类User,基本字段如下
- 简单类型
- 复杂类型
- 实体类eclipse模板
- 实体类Idea模板
6.全部注释列表
@Api
Api 标记可以标记一个Controller类做为swagger 文档资源,使用方式
属性名称
|
备注
|
---|---|
value | url的路径值 |
tags | 如果设置这个值、value的值会被覆盖 |
description | 对api资源的描述 |
basePath | 基本路径可以不配置 |
position | 如果配置多个Api 想改变显示的顺序位置 |
produces | For example, “application/json, application/xml” |
consumes | For example, “application/json, application/xml” |
protocols | Possible values: http, https, ws, wss. |
authorizations | 高级特性认证时配置 |
hidden | 配置为true 将在文档中隐藏 |
@ApiOperation每一个url资源的定义,使用方式
属性名称
|
备注
|
---|---|
value | url的路径值 |
tags | 如果设置这个值、value的值会被覆盖 |
description | 对api资源的描述 |
basePath | 基本路径可以不配置 |
position | 如果配置多个Api 想改变显示的顺序位置 |
produces | For example, “application/json, application/xml” |
consumes | For example, “application/json, application/xml” |
protocols | Possible values: http, https, ws, wss. |
authorizations | 高级特性认证时配置 |
hidden | 配置为true 将在文档中隐藏 |
response | 返回的对象 |
responseContainer | 这些对象是有效的 “List”, “Set” or “Map”.,其他无效 |
httpMethod | “GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH” |
code | http的状态码 默认 200 |
extensions | 扩展属性 |
@ApiParam标记
public ResponseEntity createUser(@RequestBody @ApiParam(value = “user”, required = true) User user)
属性名称
|
备注
|
---|---|
name | 属性名称 |
value | 属性值 |
defaultValue | 默认属性值 |
allowableValues | 可以不配置 |
required | 是否属性必填 |
access | 不过多描述 |
allowMultiple | 默认为false |
hidden | 隐藏该属性 |
example | 举例子 |
@ApiImplicitParam对容器的描述
属性名称
|
备注
|
---|---|
name | 属性名称 |
value | 属性值 |
defaultValue | 默认值 |
allowableValues | 可以不可配置 |
required | 是否属性必填 |
access | 不可过多描述 |
allowMutiple | 默认为false |
dataType | 数据类型 |
paramType | 参数类型 |
@ApiResponse
属性名称
|
备注
|
---|---|
code | http的状态码 |
message | 描述 |
response | 默认响应类 Void |
reference | 参考ApiOperation中配置 |
responseHeaders | 参考 ResponseHeader 属性配置说明 |
responseContainer | 参考ApiOperation中配置 |
@ResponseHeader(name=”head1”,description=”response head conf”)
属性名称
|
备注
|
---|---|
name | 响应头名称 |
description | 头描述 |
response | 默认响应类 Void |
responseContainer | 参考ApiOperation中配置 |
7.文档编写规范建议
- entity的描述
@ApiModel(description = “我是描述”,value = “用户”)
对实体的描述
description:在v2/api-docs的实体看到描述,
value的值在@ApiImplicitParam注解中的dataType可用,
@ApiModelProperty(value = “用户姓名”,required = true,dataType = “String”)
private String name;
对字段的描述
value:1,入参和出参的ModelModel Schema选项卡可见,2,在v2/api-docs的实体字段描述可见
required:该属性是否必填写
dataType:该字段的数据类型
- controller的描述
@Api(value = “API”, description = “用户接口详情”,tags=”A”)
对controler的描述
value:访问某个controller的url的根路径值
description:对于该controller的的大概描述
tags:把api接口进行分分组
@ApiOperation(value = “获取用户详细信息”, notes = “根据url的id来获取用户详细信息”,httpMethod =”GET”)
对该方法的描述
value:主页面中对该接口的描述,位置在接口的最右边
notes:点开接口后,第一段描述。
httpMethod:HTTP请求的动作名,可选值有:”GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”。
@ApiImplicitParam(name = “id”, value = “用户ID”, required = true, dataType = “String”, paramType = “path”)
对参数的描述,如果多个参数需要用@ApiImplicitParams对其进行包裹
name:参数名称
value:参数的简短描述
required:是否必须传递的参数
dataType:参数类型,可以为类名,也可以为基本类型(String,int,Boolean)
paramType:参数的传入(请求)类型,可选的值有path, query, body, header or form。(如果在路径中提取参数用path比如:在/A/{XXX}路径中得到XXX的值)
@ApiParam(name = “user”, value = “userValue”, required = true)
对参数元信息的说明,一般这个注解只能被使用在JAX-RS 1.x/2.x的综合环境下,和ApiImplicitParam注解类似
required:该参数是否必填
value:该参数的简短介绍
@ApiResponse(code = 200, message = “Successful — 请求已完成”)
返回状态码的描述,如果有多个可以使用@ApiResponses注解进行包裹
code:服务器返回的状态码
message:服务器返回状态码的简短说明
sample:header中传递token
@ApiImplicitParams({@ApiImplicitParam(name = "TOKEN", value = "Authorization token", required = true, dataType = "string", paramType = "header")})