Swagger

一、背景

在前后端分离开发中通常由后端程序员设计接口，完成后需要编写接口文档，最后将文档交给前端工程师，前端工程师参考文档进行开发。

二、什么是Swagger

OpenAPI规范（OpenAPI Specification 简称OAS）是Linux基金会的一个项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程，目前版本是V3.0，并且已经发布并开源在github上。

（https://github.com/OAI/OpenAPI-Specification）

        Swagger是全球最大的OpenAPI规范（OAS）API开发工具框架，Swagger是一个在线接口文档的生成工具，前后端开发人员依据接口文档进行开发。 (API Documentation & Design Tools for Teams | Swagger)

Spring Boot 可以集成Swagger，Swaager根据Controller类中的注解生成接口文档 ，只要添加Swagger的依赖和配置信息即可使用它。

三、使用流程

3.1 依赖

    com.spring4all
    swagger-spring-boot-starter

3.2 配置文件

在 bootstrap.yml中配置swagger的扫描包路径及其它信息，base-package为扫描的包路径，扫描Controller类。

swagger:
  title: "学成在线内容管理系统"
  description: "内容系统管理系统对课程相关信息进行管理"
  base-package: com.xuecheng.content
  enabled: true
  version: 1.0.0

3.3 启动类添加注解

在启动类中添加@EnableSwagger2Doc注解

3.4 接口描述信息

@Api：修饰整个类，描述Controller的作用
 @ApiOperation：描述一个类的一个方法，或者说一个接口
 @ApiParam：单个参数描述
 @ApiModel：用对象来接收参数
 @ApiModelProperty：用对象接收参数时，描述对象的一个字段
 @ApiResponse：HTTP响应其中1个描述
 @ApiResponses：HTTP响应整体描述
 @ApiIgnore：使用该注解忽略这个API
 @ApiError ：发生错误返回的信息
 @ApiImplicitParam：一个请求参数
 @ApiImplicitParams：多个请求参数

示例：

@RestController
@Api(value = "课程信息编辑接口",tags = "课程信息编辑接口")
public class CourseBaseInfoController {
    @ApiOperation("课程查询接口")
    @PostMapping("course/list")
//    @RequestBody是SpringMVC中的注解，用于将HTTP请求的请求体(body)中的JSON/XML格式的数据转换成Java对象。required=false表示此参数不是必填项
    public PageResult List(PageParams pageParams, @RequestBody(required=false) QueryCourseParamsDto queryCourseParamsDto){

        return  null;
    }
}

public class PageParams {

    //当前页码
    @ApiModelProperty("当前页码")
    private Long pageNo = 1L;

    //每页记录数默认值
    @ApiModelProperty("当前记录条数")
    private Long pageSize =10L;


}

访问http://localhost:63040/content/swagger-ui.html

有如下添加了中文注释的接口信息

 右上角Try it out 可以进行接口测试