Swagger的介绍
OpenAPI是一个编写API文档的规范,然而如果手动去编写OpenAPI规范的文档,是非常麻烦的。而Swagger就是一个实现了OpenAPI规范的工具集。
Swagger的官网与帮助文档 https://swagger.io/resources/open-api/
引入依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
数据格式
Common Name | type | format | Comments |
---|---|---|---|
integer | integer | int32 | signed 32 bits |
long | integer | int64 | signed 64 bits |
float | number | float | |
double | number | double | |
string | string | ||
byte | string | byte | base64 encoded characters |
binary | string | binary | any sequence of octets |
boolean | boolean | ||
date | string | date | As defined by full-date - RFC3339 |
dateTime | string | date-time | As defined by date-time - RFC3339 |
password | string | password | Used to hint UIs the input needs to be obscured. |
Swagger的属性
字段名称 | 类型 | 描述 |
---|---|---|
swagger | string | 必需的。 指定正在使用的 Swagger 规范版本。 Swagger UI 和其他客户端可以使用它来解释 API 列表。 该值必须是 "2.0" . |
info | 信息对象 | 必需的。 提供有关 API 的元数据。 如果需要,客户端可以使用元数据。 |
host | string | 为 API 提供服务的主机(名称或 IP)。 这必须仅是主机,不包括方案或子路径。 它可以包括一个端口。 如果 host 不包括在内,将使用提供文档的主机(包括端口)。 这 host 不支持 路径模板 。 |
basePath | string | 提供 API 的基本路径,它相对于 host . 如果未包含,则直接在 host . 该值必须以前导斜杠 ( / )。 这 basePath 不支持 路径模板 。 |
schemes | [ string ] | API 的传输协议。 值必须来自列表: "http" , "https" , "ws" , "wss" . 如果 schemes 不包括在内,要使用的默认方案是用于访问 Swagger 定义本身的方案。 |
consumes | [ string ] | API 可以使用的 MIME 类型列表。 这对所有 API 都是全局的,但可以在特定 API 调用上被覆盖。 值必须如 下所述 Mime Types 。 |
produces | [ string ] | API 可以生成的 MIME 类型列表。 这对所有 API 都是全局的,但可以在特定 API 调用上被覆盖。 值必须如 下所述 Mime Types 。 |
paths | 路径对象 | 必需的。 API 的可用路径和操作。 |
definitions | 定义对象 | 一个对象,用于保存操作产生和使用的数据类型。 |
parameters | 参数定义对象 | 保存可跨操作使用的参数的对象。 此属性 不 为所有操作定义全局参数。 |
responses | 响应定义对象 | 保存可跨操作使用的响应的对象。 此属性 不 为所有操作定义全局响应。 |
securityDefinitions | 安全定义对象 | 可在整个规范中使用的安全方案定义。 |
tags | [ 安全需求对象 ] | 将哪些安全方案应用于整个 API 的声明。 值列表描述了可以使用的替代安全方案(即,安全要求之间存在逻辑 OR)。 单个操作可以覆盖此定义。 |
标签 | [ 标签对象 ] | 规范使用的带有附加元数据的标签列表。 标签的顺序可以被解析工具用来反映它们的顺序。 并非 使用的所有标签都 操作对象 必须声明。 未声明的标签可能是随机组织的,也可能是基于工具的逻辑。 列表中的每个标签名称必须是唯一的。 |
外部文档 | 外部文档对象 | 额外的外部文档。 |
信息对象
该对象提供有关 API 的元数据。 如果需要,客户端可以使用元数据,并且可以在 Swagger-UI 中提供方便。
字段名称 | 类型 | 描述 |
---|---|---|
标题 | string | 必需的。 应用程序的标题。 |
描述 | string | 应用程序的简短描述。 GFM 语法 可用于富文本表示。 |
服务条款 | string | API 的服务条款。 |
接触 | 联系对象 | 公开 API 的联系信息。 |
执照 | 许可对象 | 公开 API 的许可信息。 |
版本 | string | 必需 提供应用程序 API 的版本(不要与规范版本混淆)。 |
title: Swagger Sample App
description: This is a sample server Petstore server.
termsOfService: http://swagger.io/terms/
contact:
name: API Support
url: http://www.swagger.io/support
email: support@swagger.io
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.1
编写配置(Swagger 与信息对象):
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.host("http://order.nc.com")
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.nc.order.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("jd商城订单系统")
.description("jd商城订单系统接口文档")
.version("1.0.0")
.build();
}
}
联系对象
公开 API 的联系信息。
固定字段
字段名称 | 类型 | 描述 |
---|---|---|
name | string | 联系人/组织的识别名称。 |
url | string | 指向联系信息的 URL。 必须采用 URL 格式。 |
string | 联系人/组织的电子邮件地址。 必须采用电子邮件地址的格式。 |
Example:
name: API Support
url: http://www.swagger.io/support
email: support@swagger.io
许可对象
公开 API 的许可信息。
固定字段
字段名称 | 类型 | 描述 |
---|---|---|
name | string | 必需的。 用于 API 的许可证名称。 |
url | string | 用于 API 的许可证的 URL。 必须采用 URL 格式。 |
许可证对象示例:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
常用注解
/**
@Api:修饰整个类,描述Controller的作用
@ApiOperation:描述一个类的一个方法,或者说一个接口
@ApiParam:单个参数描述
@ApiModel:用对象来接收参数
@ApiProperty:用对象接收参数时,描述对象的一个字段
@ApiResponse:HTTP响应其中1个描述
@ApiResponses:HTTP响应整体描述
@ApiIgnore:使用该注解忽略这个API
@ApiError :发生错误返回的信息
@ApiImplicitParam:一个请求参数
@ApiImplicitParams:多个请求参数
*/
接口声明
在controller的每个handler上添加接口说明注解:
@RestController
@RequestMapping("order")
@Api("订单服务接口")
public class OrderController {
@Autowired
private OrderService orderService;
@Autowired
private PayHelper payHelper;
/**
* 分页查询当前用户订单
*
* @param status 订单状态
* @return 分页订单数据
*/
@GetMapping("list")
@ApiOperation(value = "分页查询当前用户订单,并且可以根据订单状态过滤",
notes = "分页查询当前用户订单")
@ApiImplicitParams({
@ApiImplicitParam(name = "page", value = "当前页",
defaultValue = "1", type = "Integer"),
@ApiImplicitParam(name = "rows", value = "每页大小",
defaultValue = "5", type = "Integer"),
@ApiImplicitParam(
name = "status",
value = "订单状态:1未付款,2已付款未发货,3已发货未确认,4已确认未评价,5交易关闭,6交易成功,已评价", type = "Integer"),
})
public ResponseEntity<PageResult<Order>> queryUserOrderList(
@RequestParam(value = "page", defaultValue = "1") Integer page,
@RequestParam(value = "rows", defaultValue = "5") Integer rows,
@RequestParam(value = "status", required = false) Integer status) {
PageResult<Order> result = this.orderService.queryUserOrderList(page, rows, status);
if (result == null) {
return new ResponseEntity<>(HttpStatus.NOT_FOUND);
}
return ResponseEntity.ok(result);
}
}
启动服务,然后访问:http://localhost:8089/swagger-ui.html