swagger 入门指南

1. 写在最前面

最近在负责的服务，出现了客户接二连三的投诉 api 参数难以理解的问题。本着从「根本上解决问题」的思路，笔者思考了以下方案：

• 简化难以理解的参数，重新设计一版 api

• 优化 api 文档，更易于用户理解

1.1 方案选择

1.1.1 优缺点分析：

• 重新设计 api 是不行的，时间紧，任务重，需求已经排到了下个月，无法投入更多的资源做 api 的重构

• 优化 api 文档也不行，原始的 api 参数设计的过于复杂，简单的从优化描述 api 入手无法根治问题，治标不治本

1.1.2 最终方案

• 抽象现有的 api 参数，对客户隐藏其不需要的部分

• 基于 swagger 构建一个客户填写必须参数，生成复杂 body 的 server

本着「不能重复踩坑」的原则，下次有设计 api 的机会，一定要多站在用户侧考虑，减少想当然的「开发者」思维（ps: 本次 api 设计非笔者完成

2. 安装

为什么把 「安装」单独拎出来，是因为笔者用的是 m1 的芯片，安装的时候，踩了个小坑，不过是小问题，但是列出来可以让其他需要安装的小伙伴做个参考。

完整的安装步骤：

 download_url=$(curl -s https://api.github.com/repos/go-swagger/go-swagger/releases/latest | \\n  jq -r '.assets[] | select(.name | contains("'"$(uname | tr '[:upper:]' '[:lower:]')"'_arm64")) | .browser_download_url')

 sudo curl -o /usr/local/bin/swagger 

sudo chmod +x /usr/local/bin/swagger

注意：要选择跟本机匹配的芯片，笔者这里选择的是 _arm64

3. 方案实施

在介绍最终的 sever 之前，先来浅浅的介绍一下 swagger 。笔者之前对于 swagger 的印象单纯的停留在可以在「代码里写符合 swagger 格式的注释，然后生成 api 文档」，这样文档和代码是一体的，方便了版本回溯和内容维护。

但是，实时上 swagger 的功能远远不知于此。 swagger 提供了两种能力：

• Generate spec from source

• Generate code from spec

注：笔者之前对 swagger 的认知停留在了「Generate spec from source」

除此之外，swagger 给 api 开发者提供了两个很好的开发思路：

• Design first approach 即设计先行

  基于这个思路，前后端在合作开发时，前端可以基于 swagger mock 的数据进行开发，不必强依赖后端准备好接口

• Code first approach 即代码先行

  基于这个思路，后端可以将版本迭代的背景信息嵌入代码中，重新生成 swagger 文档，这个就是代码先行

3.1 generate code from spec 介绍

3.1.1 生成 & 运行 demo

spec 描述文件：

---
swagger: '2.0'
info:
  version: 1.0.0
  title: Greeting Server
paths:
  /hello:
    get:
      produces:
        - text/plain
      parameters:
        - name: name
          required: false
          type: string
          in: query
          description: defaults to World if not given
      operationId: getGreeting
      responses:
        200:
          description: returns a greeting
          schema:
              type: string
              description: contains the actual greeting as plain text

• 新建目录 GreetServer

• 将上述的内容拷贝为 swagger.yaml 文件，并放在 GreetServer 目录下

• 运行如下命令

   swagger generate server  -f swagger.yaml
  

• 即可得到如下目录结构的文件

  

• 如下图所示，就得到一个可以快速运行的 demo

  

  注：上述 demo 的运行效果返回的是该方法还没有实现

• 快速在上述 demo 中增加逻辑的方式，过滤 「safe」关键字，在代码中简单返回 body

  

• 运行效果

  

3.2 实践之生成复杂 body

笔者遇到的问题是：

• api body 的 json 层级复杂且手动拼写的时候很容易出错

• api body 不同功能的参数混合在同一大的 body ，用户在理解上比较复杂

• api body 的参数校验错误，很多是通过 ncs 异步回调通知的方式，客户在集成的时候很难发现问题

解决方法：

• 按照功能维度，场景化 api 的 body 体同时精简 body 生成的必须参数，减少客户理解的成本

• 生成 body 的过程中同步校验 body 的合法性，给客户返回直接可「自修正」的错误描述

使用例子说明：

• 用户使用极简的 rqst body

  

• 返回可以直接调用的 resp boy

  

4. 碎碎念

二阳 + 要好的小伙伴选择回归二线工作，总觉得心情跟梅雨季的天气一样闷闷的

• 既然相遇是偶然，又何必在意分别时的突然呢

• 我们终究会在各种事与愿违中学会自渡

• 有个思想者叫做克里希那穆提，他写了一段话说，夕阳没有意义，可是你对夕阳会感受深刻。好吃的东西没有意义，可是你吃到好吃的东西的时候会感受深刻。 他说人生也是一样的，人生没有意义，可是你会感受深刻。他说这不表示它不值得活下去，它值得活，可它跟意义无关。

5. 参考资料

• go-swagger install

• go-swagger tutorials

• go-swagger 使用说明

• Generate Swagger Doc Files From Go Code Using Go-swagger