Swagger结合SpringBoot的使用

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 格式。
email	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