Spring整合swagger-ui

1.添加依赖

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger2</artifactId>

<version>2.2.2</version>

</dependency>

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger-ui</artifactId>

<version>2.2.2</version>

</dependency>

2.添加配置类

@EnableSwagger2

@Configuration

@Component

public class SwaggerConfig {

@Bean

public Docket createRestApi() {

return new Docket(DocumentationType.SWAGGER_2)

.apiInfo(apiInfo())

.select()

.apis(RequestHandlerSelectors.basePackage("com.***.api.ninth.controller"))//扫描com路径下的api文档

.paths(PathSelectors.any())//路径判断

.build();

}

private ApiInfo apiInfo() {

return new ApiInfoBuilder()

.title("shendu api")//标题

.description("接口 api")//描述

.termsOfServiceUrl("http://ddkdkdk.com")//（不可见）条款地址

.contact("kenny")//作者信息

.version("1.0.1")//版本号

.build();

}

}

<bean class="com.**.ui.SwaggerConfig" />

3.在controller中添加相关的注释

1）在类上添加

@Api(value = "API - VehiclesController", description = "版本接口详情")

@Controller

@RequestMapping("/ninth/version")

public class VersionController {}

2）在方法上添加

@ApiOperation(value = "获取飞机和APP的最新版本", httpMethod = "GET", response = JSONObject.class, notes = "updateVersion")

@RequestMapping(value="updateVersion",method = RequestMethod.POST)

@ResponseBody

public Object updateVersion(

@ApiParam(required = false, name="appVersionNumber", value = "app版本号")Integer appVersionNumber){}

4.访问地址

localhost:8888/swagger-ui.html

全部注释列表

@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中配置

4文档编写规范建议

• 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")})