引言

相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档和实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用前端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常还会抱怨别人写的代码没有写注释，然而自己写起代码来，最讨厌的也是写注释。所以仅仅只听过强制了来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。

1. 什么是Swagger

发现了痛点就要去找解决方案。解决方案用的人多了，就成了标准的规范，这就是Swagger的由来。通过这套规范，你只需要按照它的规范去定义接口及接口相关信息。再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多做语言的客户端和服务端的代码，以及在线接口调试页面等等。这样，如果按照新的开发木事，在开发新版本或者迭代版本的时候，只需要更新Swagger描述文件，就可以自动生成接口文档和客户端代码，做到调用端代码、服务端代码以及接口文档的一致性。
但即便如此，对于许多开发来说，编写这个yml或json格式的描述文件，本身也是有一定负担的工作，特别是在后面持续迭代开发的时候，往往会忽略更新这个描述文件，直接更改代码。久而久之，这个描述文件也和实际项目渐行渐远，基于该描述文件生成的接口文档也失去了参考意义。所以作为Java界服务端的大一统框架Spring，迅速将Swagger规范纳入自身的标准，建立了Spring-swagger项目，后面改成了现在的Springfox。通过在项目中引入Springfox，可以扫描相关的代码，生成该描述文件，进而生成与代码一致的接口文档和客户端代码。这种通过代码生成接口文档的形式，在后面需求持续迭代的项目中，显得尤为重要和高效。
作用：
1. 接口的文档在线自动生成。
2. 功能测试。
目标：
Swagger™的目标是为REST APIs定义一个标准的,与语言无关的接口,使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下能发现和理解各种服务的功能。
image.png
总结：Swagger是一个用来定义接口标准，接口规范，同时能根据你的代码自动生成接口说明文档的一个工具。

2. 官方提供的工具

image.png

  • Swagger Codegen：通过Codegen可以将描述文件生成html格式和cwiki形式的接口文档，同时也能生成多种语言的服务端和客户端代码。支持通过jar包、docker、node等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。
  • Swagger UI：提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。
  • Swagger Editor：类似于Markdown编辑器的编辑Swagger描述文件的编辑器，该编辑器支持实时预览描述文件的更新效果，也提供了在线编辑器和本地部署器俩种方式。
  • Swagger Inspector：感觉和Postman差不多，是一个可以对接口进行测试的在线版的postman。比如在Swagger UI里面做接口请求，会返回更多的信息，也会保存你请求的实际请求参数等数据。
  • Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

  • Springfox Swagger：Spring基于Swagger规范，可以将基于SpringMVC和Spring Boot项目的项目代码，自动生成JSON格式的描述文件。本身不是属于Swagger官网提供的，在这里列出来做个说明，方便后面作一个使用的展开。

    3. 构建Swagger与Spring Boot环境

    3.1. 引入依赖

    1. <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
    2. <dependency>
    3.   <groupId>io.springfox</groupId>
    4.   <artifactId>springfox-swagger2</artifactId>
    5.   <version>2.9.2</version>
    6. </dependency>
    7. <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
    8. <dependency>
    9.   <groupId>io.springfox</groupId>
    10.   <artifactId>springfox-swagger-ui</artifactId>
    11.   <version>2.9.2</version>
    12. </dependency>

    3.2. 编写Swagger配置类

  • 示例1 ```java import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration @EnableSwagger2
public class SwaggerConfig {

  1. @Bean
  2. public Docket createRestApi(){
  3.     return new Docket(DocumentationType.SWAGGER_2)
  4.             .pathMapping("/")
  5.             .select()
  6.             // 扫描哪个接口的包
  7.             .apis(RequestHandlerSelectors.basePackage("com.baiyi.controller"))
  8.             .paths(PathSelectors.any())
  9.             .build().apiInfo(new ApiInfoBuilder()
  10.                     .title("标题: SpringBoot 整合 Swagger 使用")
  11.                     .description("详细信息: SpringBoot 整合 Swagger,详细信息......")
  12.                     // 版本信息
  13.                     .version("1.1")
  14.                     // 开发文档的联系人
  15.                     .contact(new Contact("baiyi", "http://www.baidu.com","1101293873@qq.com"))
  16.                     .license("This Baidu License")
  17.                     .licenseUrl("http://www.baidu.com")
  18.                     .build());
  19. }

}

  2. - **示例2**
  3. ```java
  4. package com.bocom.bdap.cmwp.config;
  6. import org.springframework.context.annotation.Bean;
  7. import org.springframework.context.annotation.Configuration;
  8. import springfox.documentation.builders.ApiInfoBuilder;
  9. import springfox.documentation.builders.PathSelectors;
  10. import springfox.documentation.builders.RequestHandlerSelectors;
  11. import springfox.documentation.service.ApiInfo;
  12. import springfox.documentation.service.Contact;
  13. import springfox.documentation.spi.DocumentationType;
  14. import springfox.documentation.spring.web.plugins.Docket;
  15. import springfox.documentation.swagger2.annotations.EnableSwagger2;
  17. @Configuration
  18. @EnableSwagger2
  19. public class Swagger2Config {
  21.     // api接口包扫描路径
  22.     public static final String SWAGGER_SCAN_BASE_PACKAGE = "com.bocom.bdap.cmwp.web.api";
  24.     public static final String VERSION = "1.0.0";
  26.     @Bean
  27.     public Docket createRestApi() {
  28.         return new Docket(DocumentationType.SWAGGER_2)
  29.                 .apiInfo(apiInfo())
  30.                 .groupName("Swagger2 API")
  31.                 .select()
  32.                 .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
  33.                 .paths(PathSelectors.any()) // 可以根据url路径设置哪些请求加入文档，忽略哪些请求
  34.                 .build();
  35.     }
  37.     private ApiInfo apiInfo() {
  38.         return new ApiInfoBuilder()
  39.                 .title("客户经理工作平台") // 设置文档的标题
  40.                 .description("Swagger2 API接口文档") // 设置文档的描述
  41.                 .version(VERSION) // 设置文档的版本信息-> 1.0.0
  42.                 .contact(new Contact("polaris", "http://localhost:8080/swagger-ui.html","450733605@qq.com")) // 开发文档的联系人
  43.                 .termsOfServiceUrl("https://www.yuque.com/polaris-docs/knowledge/swagger2")
  44.                 .license("Apache 2.0")
  45.                 .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0") // 设置文档的License信息
  46.                 .build();
  47.     }
  49. }

3.3. 启动SpringBoot项目

image.png

3.4. 访问Swagger的UI界面

image.png

4. 使用Swagger构建

4.1. 开发Controller接口

  1. import org.springframework.web.bind.annotation.GetMapping;
  2. import org.springframework.web.bind.annotation.RequestMapping;
  3. import org.springframework.web.bind.annotation.RestController;
  5. import java.util.HashMap;
  6. import java.util.Map;
  8. @RestController
  9. @RequestMapping("/user")
  10. public class HelloController {
  12.     @GetMapping("/findAll")
  13.     public Map<String,Object> findAll(){
  14.         Map<String, Object> map = new HashMap<>();
  15.         map.put("success", "查询所有数据成功");
  16.         map.put("status", true);
  17.         return map;
  18.     }
  19. }

4.2. 重启项目访问接口界面

image.png

5. Swagger注解

作用范围 API 使用位置
对象属性 @ApiModelProperty 用在参数对象的字段上
协议集描述 @Api 用在Controller类上
协议描述 @ApiOperation 用在controller方法上
Response集 @ApiResponses 用在controller方法上
Response @ApiResponse 用在@ApiResponses里面
非对象参数集 @ApilmplicitParams 用在controller方法上
非对象参数描述 @ApilmplicitParam 用在@ApilmplicitParams的方法里边
描述返回对象的意义 @ApiModel 用在返回对象类上
对象属性、协议/集描述 @ApiIgnore 忽略类、方法和属性

5.1. @Api

  • 作用：用来指定接口的描述文字

  • 修饰范围：用在类上

    1. @RequestMapping("/user")
    2. @Api(tags = "用户服务相关接口描叙")
    3. public class HelloController {
    5.       ....
    6. }

    5.2. @ApiOperation

  • 作用：用来对接口中具体方法做描叙

  • 修饰范围：用在方法上

    1. @GetMapping("/findAll")
    2. @ApiOperation(value = "查询所有用户接口",
    3.       notes = "<span style='color:red;'>描叙:</span>&nbsp;&nbsp;用来查询所有用户信息的接口")
    4. public Map<String,Object> findAll(){
    5.   Map<String, Object> map = new HashMap<>();
    6.   map.put("success", "查询所有数据成功");
    7.   map.put("status", true);
    8.   return map;
    9. }

    5.3. @ApiImplicitParams

  • 作用：用来接口中参数进行说明

  • 修饰范围：用在方法上

    5.3.1. 普通参数使用

    1. @PostMapping("save")
    2. @ApiOperation(value = "保存用户信息接口",
    3.       notes = "<span style='color:red;'>描叙:</span>&nbsp;&nbsp;用来保存用户信息的接口")
    4. @ApiImplicitParams({
    5.       @ApiImplicitParam(name = "id", value = "用户 id", dataType = "String", defaultValue = "21"),
    6.       @ApiImplicitParam(name = "name", value = "用户姓名", dataType = "String", defaultValue = "白衣")
    7. })
    8. public Map<String, Object> save(String id, String name) {
    9.   System.out.println("id = " + id);
    10.   System.out.println("name = " + name);
    11.   Map<String, Object> map = new HashMap<>();
    12.   map.put("id", id);
    13.   map.put("name", name);
    14.   return map;
    15. }
    image.png

    5.3.2. RestFul风格使用

    如果使用的是RestFul风格进行传参，必须再添加一个paramType=”path”。
    1. @PostMapping("save/{id}/{name}")
    2. @ApiOperation(value = "保存用户信息接口",
    3.       notes = "<span style='color:red;'>描叙:</span>&nbsp;&nbsp;用来保存用户信息的接口")
    4. @ApiImplicitParams({
    5.       @ApiImplicitParam(name = "id", value = "用户 id", dataType = "String", defaultValue = "21", paramType = "path"),
    6.       @ApiImplicitParam(name = "name", value = "用户姓名", dataType = "String", defaultValue = "白衣", paramType = "path")
    7. })
    8. public Map<String, Object> save(@PathVariable("id") String id,@PathVariable("name") String name) {
    9.   System.out.println("id = " + id);
    10.   System.out.println("name = " + name);
    11.   Map<String, Object> map = new HashMap<>();
    12.   map.put("id", id);
    13.   map.put("name", name);
    14.   return map;
    15. }
    image.png

    5.3.3. JSON格式使用

    如果是RequestBody的方式，需要定义一个对象进行接收。

  1. 定义一个User对象。

    1. @Data
    2. @AllArgsConstructor
    3. @NoArgsConstructor
    4. public class User {
    5.  private String id;
    6.  private String name;
    7. }

  2. 编写Controller。

    1. @PostMapping("save2")
    2. public Map<String, Object> save2(@RequestBody User user) {
    3.  System.out.println("id = " + user.getId());
    4.  System.out.println("name = " + user.getName());
    5.  Map<String, Object> map = new HashMap<>();
    6.  map.put("id", user.getId());
    7.  map.put("name", user.getName());
    8.  return map;
    9. }

  3. 重启项目，打开 UI 界面

image.png
测试：
image.png

5.4. @ApiResponses

  • 作用：用在请求的方法上，表示一组响应

  • 修饰范围：用在方法上

    1. @PostMapping("save2")
    2. @ApiResponses({
    3.       @ApiResponse(code = 404, message = "请求路径不对"),
    4.       @ApiResponse(code = 400, message = "程序不对")
    5. })
    6. public Map<String, Object> save2(@RequestBody User user) {
    7.   System.out.println("id = " + user.getId());
    8.   System.out.println("name = " + user.getName());
    9.   Map<String, Object> map = new HashMap<>();
    10.   map.put("id", user.getId());
    11.   map.put("name", user.getName());
    12.   return map;
    13. }

    5.5. @ApiModelProperty

  • 作用：用在参数对象的字段上

  • 修饰范围：对象属性 ```java /**
    • 获取城市编号
    • @return 城市编号 */ @ApiModelProperty(value=”城市编号”,example=”058”,required=true) public String getCode() { return code; }

/**

  • 设置城市编号
  • @param code 城市编号 */ public void setCode(String code) { this.code = code; }

/**

  • 获取城市名称
  • @return 城市名称 */ @ApiModelProperty(value=”城市名称”,example=”guangZhou”,required=true) public String getName() { return name; } ```

  • 参数说明

    • value：字段说明
    • name：重写属性名字
    • dataType：重写属性类型
    • required：是否必填
    • example：举例说明
    • hidden：隐藏

      5.6. @ApiIgnore

  • 作用：忽略类、方法和参数

  • 修饰范围：类、方法和参数 ```java // 忽略整个类 @ApiIgnore @RestController @RequestMapping(value = “/api”) public class XttblogController {

    // 忽略整个方法 @ApiIgnore public String hello(){ return “hello”; }

    // 忽略User参数 public String sayHello(@ApiIgnore User user){ return “hello “ + user.getName(); }

}

  1. <a name="G15NR"></a>
  2. # 6. 综合应用
  3. <a name="obtVH"></a>
  4. ## 1. Java对象
  5. ```java
  6. package com.bocom.bdap.cmwp.domain;
  8. import com.bocom.bdap.cmwp.common.Constants;
  9. import io.swagger.annotations.ApiModel;
  10. import io.swagger.annotations.ApiModelProperty;
  11. import org.springframework.data.annotation.Transient;
  12. import javax.persistence.Entity;
  13. import javax.persistence.GeneratedValue;
  14. import javax.persistence.Id;
  15. import javax.persistence.Table;
  17. @Entity
  18. @Table(name = Constants.TableName.CMWP_CUSTOMERS_MILESTONE, schema = Constants.SCHEMA.BDAP_CMWP_SCHEMA)
  19. @ApiModel(description = "客户名下户口重要事件表")
  20. public class CustomersMilestone {
  22.     @Id
  23.     @GeneratedValue
  24.     private String id;
  25.     private String customersId;
  26.     private String customersName;
  27.     private String param1;
  28.     private String param2;
  29.     private String param3;
  30.     private String param4;
  31.     private String param5;
  32.     private String param6;
  33.     private String typeId;
  34.     private String typeName;
  35.     private String eventDate;
  36.     private String loginName;
  38.     @Transient
  39.     private Integer page;
  40.     @Transient
  41.     private Integer size;
  43.     @ApiModelProperty(value="主键")
  44.     public String getId() {
  45.         return id;
  46.     }
  48.     public void setId(String id) {
  49.         this.id = id;
  50.     }
  52.     @ApiModelProperty(value="客户编号",example="1")
  53.     public String getCustomersId() {
  54.         return customersId;
  55.     }
  57.     public void setCustomersId(String customersId) {
  58.         this.customersId = customersId;
  59.     }
  61.     @ApiModelProperty(value="客户名称",example="张三")
  62.     public String getCustomersName() {
  63.         return customersName;
  64.     }
  66.     public void setCustomersName(String customersName) {
  67.         this.customersName = customersName;
  68.     }
  70.     @ApiModelProperty(value="类型编号",example="1")
  71.     public String getTypeId() {
  72.         return typeId;
  73.     }
  75.     public void setTypeId(String typeId) {
  76.         this.typeId = typeId;
  77.     }
  79.     @ApiModelProperty(value="类型名称",example="其他渠道")
  80.     public String getTypeName() {
  81.         return typeName;
  82.     }
  84.     public void setTypeName(String typeName) {
  85.         this.typeName = typeName;
  86.     }
  88.     @ApiModelProperty(value="事件时间",example="2021-05-31")
  89.     public String getEventDate() {
  90.         return eventDate;
  91.     }
  93.     public void setEventDate(String eventDate) {
  94.         this.eventDate = eventDate;
  95.     }
  97.     @ApiModelProperty(value="页码",example="0",required=true)
  98.     public Integer getPage() {
  99.         return page;
  100.     }
  102.     public void setPage(Integer page) {
  103.         this.page = page;
  104.     }
  106.     @ApiModelProperty(value="页数",example="10",required=true)
  107.     public Integer getSize() {
  108.         return size;
  109.     }
  111.     public void setSize(Integer size) {
  112.         this.size = size;
  113.     }
  115.     @ApiModelProperty(value="OA登录名",example="fokmingkwong")
  116.     public String getLoginName() {
  117.         return loginName;
  118.     }
  120.     public void setLoginName(String loginName) {
  121.         this.loginName = loginName;
  122.     }
  123.     @ApiModelProperty(value="信息1",example="渠道")
  124.     public String getParam1() {
  125.         return param1;
  126.     }
  128.     public void setParam1(String param1) {
  129.         this.param1 = param1;
  130.     }
  131.     @ApiModelProperty(value="信息2",example="交易类型")
  132.     public String getParam2() {
  133.         return param2;
  134.     }
  136.     public void setParam2(String param2) {
  137.         this.param2 = param2;
  138.     }
  139.     @ApiModelProperty(value="信息3",example="理财产品类型")
  140.     public String getParam3() {
  141.         return param3;
  142.     }
  144.     public void setParam3(String param3) {
  145.         this.param3 = param3;
  146.     }
  147.     @ApiModelProperty(value="信息4",example="理财产品名")
  148.     public String getParam4() {
  149.         return param4;
  150.     }
  152.     public void setParam4(String param4) {
  153.         this.param4 = param4;
  154.     }
  155.     @ApiModelProperty(value="信息5",example="理财产品代码")
  156.     public String getParam5() {
  157.         return param5;
  158.     }
  160.     public void setParam5(String param5) {
  161.         this.param5 = param5;
  162.     }
  163.     @ApiModelProperty(value="信息6",example="交易货币及金")
  164.     public String getParam6() {
  165.         return param6;
  166.     }
  168.     public void setParam6(String param6) {
  169.         this.param6 = param6;
  170.     }
  172.     @Override
  173.     public String toString() {
  174.         return "CustomersMilestone{" +
  175.                 "id='" + id + '\'' +
  176.                 ", customersId='" + customersId + '\'' +
  177.                 ", customersName='" + customersName + '\'' +
  178.                 ", typeId='" + typeId + '\'' +
  179.                 ", typeName='" + typeName + '\'' +
  180.                 ", eventDate='" + eventDate + '\'' +
  181.                 ", loginName='" + loginName + '\'' +
  182.                 ", page=" + page +
  183.                 ", size=" + size +
  184.                 '}';
  185.     }
  187. }

2. 对象参数

  1. @ApiOperation(value = "条件查询客户动态", notes = "<span style='color:red;'>描述：</span>&nbsp;&nbsp;重要事件查询", produces = "application/json")
  2. @ApiImplicitParams({
  3.     @ApiImplicitParam(name = "param", value = "客户动态对象", paramType = "body", required = true, dataType = "CustomersMilestone")
  4. })
  5. @PostMapping(value = "findPage")
  6. public Result<?> findPage(@RequestBody CustomersMilestone param, @ApiIgnore @SessionAware Session session) {
  7.     // ....
  8. }

3. Map参数

  • 方式1：@DynamicParameters

    1. @ApiOperation(value = "条件查询客户动态", notes = "<span style='color:red;'>描述：</span>&nbsp;&nbsp;重要事件查询", produces = "application/json")
    2. @DynamicParameters(name = "param" , properties = {
    3.   @DynamicParameter(name = "id", value = "主键", example = "1", dataTypeClass=String.class),
    4.   @DynamicParameter(name = "loginName", value = "OA登录名", example = "fokmingkwong", required = true, dataTypeClass=String.class),
    5.   @DynamicParameter(name = "page", value = "页码", example = "0", required = true, dataTypeClass=Integer.class),
    6.   @DynamicParameter(name = "size", value = "页数", example = "10", required = true, dataTypeClass=Integer.class)
    7. })
    8. @PostMapping(value = "findPage")
    9. public Result<?> findPage(@RequestBody Map<String, Object> param, @ApiIgnore @SessionAware Session session) {
    10.   // ....
    11. }

  • 方式2：@ApiOperationSupport

    1. @ApiOperation(value = "条件查询客户动态", notes = "<span style='color:red;'>描述：</span>&nbsp;&nbsp;重要事件查询", produces = "application/json")
    2. @ApiOperationSupport(
    3.   params = @DynamicParameters(name = "param" , properties = {
    4.       @DynamicParameter(name = "id", value = "主键", example = "1", dataTypeClass=String.class),
    5.       @DynamicParameter(name = "loginName", value = "OA登录名", example = "fokmingkwong", dataTypeClass=String.class),
    6.       @DynamicParameter(name = "page", value = "页码1", example = "10", required = true, dataTypeClass=Integer.class),
    7.       @DynamicParameter(name = "size", value = "页数1", example = "110", required = true, dataTypeClass=Integer.class)
    8.   })
    9. )
    10. @PostMapping(value = "findPage")
    11. public Result<?> findPage(@RequestBody Map<String, Object> param, @ApiIgnore @SessionAware Session session) {
    12.   // ....
    13. }

    参考

    Wiki：Swagger使用教程
    CSDN：真正在react中实现iframe引用外部链接高度自适应
    B站：一小时掌握Swagger技术
    B站：行业中主流Swagger接口管理工具，整合SpringBoot快速入门