Swagger使用教程——快速上手swagger

1.swagger简介

swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RestFul风格的web服务，总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器断的代码，允许API来始终保持同步。

2.作用

1. 接口的文档在线自动生成。

2. 功能测试。

3.使用

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

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

<!-- Spring Boot 集成 swagger -->
<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
</dependency>

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

swagger:
  title: "xxx内容管理系统"
  description: "内容管理系统对xx相关信息进行管理"
  base-package: com.xxx.content
  enabled: true
  version: 1.0.0

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

3、添加文档内容 在完成了上述配置后，其实已经可以生产文档内容，但是这样的文档主要针对请求本身，描述的主要来源是函数的命名，通常需要自己增加一些说明来丰富文档内容。

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

4.添加完注解后，启动服务，工程启动起来，访问http://localhost:63040/content/swagger-ui.html查看接口信息

示例：

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

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

     //....

  }

}

5、进行功能测试，点击try it out 可以测试接口