Swagger API 接口文档生成工具的利与弊

忘是亡心i 2022-02-24 10:28 585阅读 0赞

作为Java后台工程师其中的一员，作者深知众多的开发者没有写接口文档的习惯。尤其是一些新手，他们只想着把功能实现、和前端开发者把接口调试通就好了，没有考虑到后期的项目维护。当他们接受一个旧项目，进行二次开发的时候，突然发现看别人的代码太难了，既没有注释，也没有接口文档，看懂一块代码逻辑要大半天，时间都浪费在了读懂旧代码上了。

为了能够偷懒(不写接口文档)，开发者发明了一种神器— Swagger ，这个工具能够自动生成 API 接口文档，在线调试，非常的方便。

Swagger 官方文档: [https://swagger.io/][https_swagger.io]

[SpringBoot 2.X集成Swagger2生成 RESTFul 风格API接口文档][SpringBoot 2.X_Swagger2_ RESTFul _API]

![Swagger-1][]  
那么使用 Swagger 就可以万事大吉了吗？

作者在这里根据自己的使用情况对其做了一些总结，仅供参考。

先说优点吧，毕竟这工具确实提升了不少工作效率。

*  1 **节省了大量手写接口文档的时间**，这是最大的优势
 *  2 生成的接口文档(参考上图)可以直接在线测试，省去了使用 Postman 设置接口参数的过程，而且请求参数，返回参数一目了然
 *  3 接口按照模块已经分类好了，很清晰

Swagger 既然这么方便，那么就没有缺点了吗？不，缺点也很明显

*  1 为了能够实现自动生成接口文档，需要在代码中提前写大量的注解，生成的接口文档越清晰，写的注解越多(参考图 2)
 *  2 对于复杂功能，一个功能需要多个模块配合的情况下，联调测试将会是一件非常令人头疼的事。举个例子: 后台排课功能，这个涉及到的模块包括教师，学生，课程等等，这是在一个界面实现的，每个模块都是分开的，生成排课表这个功能涉及到以上模块，但是前端开发者不熟悉每个模块之间的联系，找到每个模块对应的接口就需要花费时间，甚至这个功能使用到哪些接口都不清楚，而 Swagger 不支持自定义接口文档，不能指明某一个功能需要使用哪些接口，有什么注意事项
 *  3 对于返回结果不能添加说明或者实现这个功能非常麻烦。虽然 Swagger 有 `@ApiResponse`  
    注解用来说明返回结果，但是这个使用并不方便，而且如果返回的并不是对象的时候(如 Map),就无法实现给每一个返回字段的说明。如果将所有的返回结果都是用对象封装，然后添加注解，这又是一个非常大的工作量
 *  4 无法测试错误的请求方式、参数等。如接口指定使用 `POST` 请求，则无法使用 swagger 测试 `GET` 请求的结果，也无法自定义 `Header`

![Swagger-2][]

那么，既然 Swagger 也有缺点，到底该不该用呢?

这个作者也给不了确定的答案，还需要开发者根据自身的情况来决定。

下边是作者不使用 Swagger 的一个接口文档解决方案,仅供参考:

**使用该文档作为一个模板，然后将每一个接口参数放到对应的位置，每一个接口保存一个文件，同一模块的接口文档放在一个文件夹下。**

模板源文件GitHub地址: [RESTful 风格 API 接口文档模板][RESTful _ API]

--------------------

## RESTful 风格 API 接口文档模板 ##

### 1 接口名称 ###

用户注册接口

### 2 接口描述 ###

*  用户信息注册
 *  用户可以通过 手机号/邮箱 进行注册
 *  同一个 手机号/邮箱只能注册一个账号

### 3 请求地址 ###

`{apiAddress}/api/user/signup`

### 4 请求方式 ###

**POST**

### 5 请求参数 ###

#### 5.1 Header 参数 ####

<table> 
 <thead> 
  <tr> 
   <th>参数名</th> 
   <th>必选</th> 
   <th>类型/参数值</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>Content-Type</td> 
   <td>是</td> 
   <td>application/json</td> 
   <td>请求参数类型</td> 
  </tr> 
 </tbody> 
</table>

#### 5.2 Body 参数 ####

<table> 
 <thead> 
  <tr> 
   <th>参数名</th> 
   <th>必选</th> 
   <th>类型</th> 
   <th>限制条件</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>account</td> 
   <td>是</td> 
   <td>string</td> 
   <td>1 &lt; length &lt; 50</td> 
   <td>用户账号</td> 
  </tr> 
  <tr> 
   <td>passcode</td> 
   <td>是</td> 
   <td>string</td> 
   <td>1 &lt; length &lt; 50</td> 
   <td>密码</td> 
  </tr> 
  <tr> 
   <td>checkCode</td> 
   <td>是</td> 
   <td>string</td> 
   <td>length = 6</td> 
   <td>验证码</td> 
  </tr> 
 </tbody> 
</table>

**注意事项**: 密码(passcode) 的加密方式为 xxxxxx

**需要调用到的其他接口**:

<table> 
 <thead> 
  <tr> 
   <th>接口名称</th> 
   <th>接口地址</th> 
   <th>用途说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>获取验证码</td> 
   <td><code>{apiAddress}/api/common/getCheckCode</code></td> 
   <td>获取注册所需验证码</td> 
  </tr> 
 </tbody> 
</table>

### 6 返回示例 ###

{ 
        "code": 200,  // 状态码
        "msg": "成功",  // 提示信息
        "data": null  // 返回内容
    }

### 7 备注 ###

更多返回错误码请查看首页返回状态码表

接口返回状态码表

--------------------

模板源文件GitHub地址: [RESTful 风格 API 接口文档模板][RESTful _ API]

个人公众号:**404Code**,分享半个互联网人的技术与思考，感兴趣的可以关注.  
![404Code][]

[https_swagger.io]: https://swagger.io/
[SpringBoot 2.X_Swagger2_ RESTFul _API]: https://blog.csdn.net/Mrqiang9001/article/details/88929446
[Swagger-1]: /images/20220224/9f4f19bb7ea1404eb83a85e376b341f7.png
[Swagger-2]: /images/20220224/713da1e54196453184da230a7d2eb9c2.png
[RESTful _ API]: https://github.com/Flying9001/Notes/blob/master/Java/RESTfulAPI%E6%8E%A5%E5%8F%A3%E6%96%87%E6%A1%A3%E6%A8%A1%E6%9D%BF.md
[404Code]: /images/20220224/b18ee6b0a7474b4dbc10b27a2834d2fd.png