Swagger生成接口文档

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

可以通过一些工具快速生成接口文档，本项目通过Swagger生成接口在线文档。

什么是Swagger？

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

（GitHub - OAI/OpenAPI-Specification: The OpenAPI Specification Repository）

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

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

1、在API工程添加swagger-spring-boot-starter依赖

Java

<dependency>
<groupId>com.spring4all</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
</dependency>

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

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

3、在启动类中添加@EnableSwagger2Doc注解

再次启动服务，工程启动起来，访问http://localhost:63040/content/swagger-ui.html查看接口信息

下图为swagger接口文档的界面：

这个文档存在两个问题：

1、接口名称显示course-base-info-controller名称不直观

2、课程查询是post方式只显示post /course/list即可。

下边进行修改，添加一些接口说明的注解，并且将RequestMapping改为PostMapping，如下：

Bash
@Api(value = "课程信息编辑接口",tags = "课程信息编辑接口")
@RestController
public class CourseBaseInfoController {

  @ApiOperation("课程查询接口")
@PostMapping("/course/list")
  public PageResult<CourseBase> list(PageParams pageParams, @RequestBody(required=false) QueryCourseParamsDto queryCourseParams){

     //....

  }

}

5、再次启动服务，工程启动起来，访问http://localhost:63040/content/swagger-ui.html查看接口信息

下图为swagger接口文档的界面：

接口文档中会有关于接口参数的说明，在模型类上也可以添加注解对模型类中的属性进行说明，方便对接口文档的阅读。

比如：下边标红的属性名称，可以通过swaager注解标注一个中文名称，方便阅读接口文档。

标注的方法非常简单：

找到模型类，在属性上添加注解：

Java
public class PageParams {
...
@ApiModelProperty("当前页码")
private Long pageNo = 1L;

@ApiModelProperty("每页记录数默认值")
private Long pageSize = 30L;
...
public class QueryCourseParamsDto {

//审核状态
@ApiModelProperty("审核状态")
private String auditStatus;
//课程名称
@ApiModelProperty("课程名称")
private String courseName;

}

重启服务，再次进入接口文档，如下图：

Swaager的常用注解如下：

在Java类中添加Swagger的注解即可生成Swagger接口，常用Swagger注解如下：

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

@ApiImplicitParam属性如下：

属性	取值	作用
paramType		查询参数类型
	path	以地址的形式提交数据
	query	直接跟参数完成自动映射赋值
	body	以流的形式提交仅支持POST
	header	参数在request headers 里边提交
	form	以form表单的形式提交仅支持POST
dataType		参数的数据类型只作为标志说明，并没有实际验证
	Long
	String
name		接收参数名
value		接收参数的意义描述
required		参数是否必填
	true	必填
	false	非必填
defaultValue		默认值

使用Swagger可以进行接口的测试。

修改接口内容，添加一些测试代码

Java
@ApiOperation("课程查询接口")
@PostMapping("/course/list")
public PageResult<CourseBase> list(PageParams pageParams, @RequestBody(required=false) QueryCourseParamsDto queryCourseParams){

    CourseBase courseBase = new CourseBase();
    courseBase.setName("测试名称");
    courseBase.setCreateDate(LocalDateTime.now());
    List<CourseBase> courseBases = new ArrayList();
    courseBases.add(courseBase);
    PageResult pageResult = new PageResult<CourseBase>(courseBases,10,1,10);
    return pageResult;

}

debug方式启动，在 return 处打断点，再用swagger请求接口。

通过下图可以看到请求参数已经正常请求至controller方法

放行继续运行，观察swagger界面，结果可以正常返回

不过存在一个问题就是LocalDateTime类型的数据转json后数据格式并不是我们要的年月日时分秒。

在base工程com.xuecheng.base.config包下加配置LocalDateTimeConfig 类实现转json时字符串与LocalDateTime类型的转换

Swagger生成接口文档

猜你喜欢