spring boot + swagger 快速简单集成
微服务API DOC 中 swagger 注解使用简单整理
spring boot + swagger的简单集成。
因为在不同版本中，注解会被解析成不同的含义，因此以2.2.2版本为基准。
部署后api-doc的json返回链接
http://localhost:8080/v2/api-docs
部署后api-doc的页面返回链接
http://localhost:8080/swagger-ui.html
springfox-swagger2 版本
2.2.2
springfox-swagger-ui 版本
2.2.2
maven依赖为：
<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>
类注解
@Api
value
controller的描述信息；
tags
controller的名称；
示例：
@Api(value = "提供用户基本信息的增删改查操作接口", tags = { "用户接口" })
public class UserController {}
在接口中返回的数据值段：
tags: [
{
name: "用户接口",
description: "提供用户基本信息的增删改查操作接口"
}
]
方法注解
@ApiOperation
produces
返回的格式类型
consumes
接收的格式类型
value
主要描述信息
notes
详细描述信息
示例：
@ApiOperation(value = "获取用户列表", notes = "获取当前数据库中存储的全部用户信息", produces="application/json", consumes = "application/json")
public List<User> getAllUserList();
在接口中返回的数据值段：
summary: "获取用户列表",
description: "获取用户的信息",
operationId: "getUserListUsingGET_1",
consumes: [
"application/json"
],
produces: [
"application/json",
"*/*"
]
@ApiImplicitParams @ApiImplicitParam
paramType
有3种类型，query、path、body；分别对应spring中的@RequestParam 、@PathVariable 、@RequestBody
name
参数名称
value
参数描述信息
defaultValue
默认值
required
是否必传
dataType
数据类型
allowableValues
允许输入的值；目前好像只针对String类型的有效
示例
@ApiImplicitParams({
@ApiImplicitParam(allowableValues = "zhangsan, lisi", paramType = "query", name = "username", value = "用户姓名", defaultValue = "zhangsan", required = true, dataType = "String"),
@ApiImplicitParam(paramType = "path", name = "id", value = "用户ID", defaultValue = "1001", required = true, dataType = "Long"),
@ApiImplicitParam(paramType = "body", name = "user", value = "用户详细信息", required = true, dataType = "User") })
public String updateUser(@RequestParam(name = "username") String username, @PathVariable Long id, @RequestBody User user);
在接口中返回的数据值段：
parameters: [
{
name: "username",
in: "query",
description: "用户姓名",
required: true,
type: "string",
default: "zhangsan",
enum: [
"zhangsan",
"lisi"
]
},
{
name: "id",
in: "path",
description: "用户ID",
required: true,
type: "integer",
default: "1001",
format: "int64"
},
{
in: "body",
name: "user",
description: "用户详细信息",
required: true,
schema: {
$ref: "#/definitions/User"
}
}
]
@ApiResponses @ApiResponse
code
httpCode编码
message
描述信息
response
返回数据类型
responseContainer
返回数据类型容器，可以选择 List Set Map
示例
@ApiResponses(value = {
@ApiResponse(code = 200, message = "更新后的用户信息"),
@ApiResponse(code = 401, message = "用户名校验错误", response = User.class),
@ApiResponse(code = 404, message = "查询的资源不存在", response = User.class) })
public List<User> updateUser(@RequestParam(name = "username") String username, @PathVariable Long id, @RequestBody User user);
responses: {
200: {
description: "更新后的全部用户信息",
schema: {
type: "array",
items: {
$ref: "#/definitions/User"
}
}
},
400: {
description: "用户名校验错误"
},
401: {
description: "Unauthorized"
},
403: {
description: "Forbidden"
},
404: {
description: "查询的资源不存在"
}
}
@ApiModelProperty
实体类属性上使用的注解，建议只使用value属性。
value
属性列描述信息
@ApiIgnore
用来标注不使用swagger的API方法。
总体描述信息
@Configuration
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.didispace.web"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建RESTful APIs")
.description("用户测试API文档")
.termsOfServiceUrl("https://luminghub.github.io/")
.contact("小明")
.version("1.0.1")
.build();
}
}
更多有用的信息，请访问：