12年经验的大龄程序员,都用什么写 API 文档

写文档，每个程序员都害怕！

技术优先，我们更倾向于将技能和精力更多地放在编写代码上，如果 API 工具不好使，不便捷，同步麻烦，测试看不懂，更会大大地打击编写文档的积极性。

什么才是好用的 API 工具呢？

最近调研了身边一些开发团队，发现他们列举的工具中，都出现过同一款工具：Eolink Apikit。

重点围绕产研需求展开：

当 API 代码更新之后，API 文档自动刷新
API 协作工具通过脚本进行自动刷新/同步

基于 API 文档智能生成请求代码和业务代码

一、Python 快速搭建 Swagger

使用 Flasgger 得到一个 Swagger UI 具体步骤，不做重点描述，咱们的目标是打通 Swagger 和 Eolink Apikit，让 API 研发资产可以盘活，Swagger 简易部署流程请参考下述步骤：

pip install flasgger

然后新建 main.py 文件，同时输入如下代码（我的本地 Python 版本为 3.8），代码有点长，可以跳过阅读，直接复制代码到本地相应文件中。

from flask import Flask
from flasgger import Swagger

app = Flask(__name__
swagger = Swagger(app


@app.route('/eolink_user_add/<user>',methods=['POST']
def eolink_user(user:
    """
    添加用户
    ---
    tags:
      - 用户相关接口
    description:
        用户注册接口，json格式
    parameters:
      - name: body
        in: body
        required: true
        schema:
          id: 添加用户
          required:
            - username
            - password
          properties:
            username:
              type: string
              description: 用户名
            password:
              type: string
              description: 密码
            phone:
              type: string
              description: 手机号
            wx:
              type: string
              description: 微信

    responses:
      201:
          description: 注册成功


          example: {'code':1,'message':注册成功}
      406:
        description: 注册失败
    """
    pass


@app.route('/eolink_opts/<t>'
def eolink_opts(t:
    """
    Eolink 功能描述
    ---
    tags:
      - 第一个测试接口
    description:
        传入大类，返回清单
    parameters:
      - m_type: number
        in: number
        type: string
        enum: ['eolink','eolink1', 'eolink2', 'eolink3']
        required: false
        default: eolink
    responses:
      200:
        description: 功能清单
        examples: {'eolink': ['一站式 API 生产力工具', '超强的 API 管理', '超方便的 API 测试']}
    """
    all_eolink_opts = {
        'eolink1': ['API 文档与研发管理', 'API 监控和异常告警', 'API 快速测试与自动化测试', 'API 微服务网关'],
        'eolink2': ['支持所有主流协议', '代码自动生成 API 文档', 'API 文档自动生成代码', 'API 版本管理', 'API 变更通知'],
        'eolink3': ['支持在线、本地、客户端进行测试', '一键进行回归/冒烟测试', '快速创建测试用例', '自动生成测试数据', '丰富详细的测试报告']
    }
    if t == 'eolink':
        result = all_eolink_opts
    else:
        result = {'eolink': all_eolink_opts.get(t}

    return result


@app.route('/', methods=['GET']
def hello(:
    return "hello world!"


if __name__ == '__main__':
    app.run(

使用 python main.py 运行 Flask 项目，然后访问 http://127.0.0.1:5000/apidocs/，
在浏览器得到如下视图，如果此时你获得界面和下图一样，那么恭喜你，准备工作已经完成！后续我们需要对上述代码进行修改，目的是在 Eolink Apikit 每次自动生成 API 文档之后，对比差异。

http://127.0.0.1:5000/apispec_1.json

在浏览器中直接打开该 URL 地址，得到如下 JSON 格式的数据，下图为部分内容展示。

二、Eolink Apikit 通过 Swagger 文件，自动生成 API 文档

进入 API 管理控制台具体项目中，在左侧菜单栏找到【其它】，然后选择【API 文档生成】。

上传前文获取的 JSON 文件到临时服务器，修改 Swagger.json 文件地址，点击确定，完成配置。

点击确定，完成来源配置，配置页面自动关闭，出现如下列表。

如果我们 JSON 文件发生了任意修改，例如【添加用户接口】新增加一个 “年龄" 参数，此时只需要点击上文提及的同步按钮，即可更新 Eolink Apikit 平台 API 详细数据。

但 Swagger 只是一个用于生成、描述和调用 RESTful 接口的 Web 服务，它远远无法满足团队中对于 API 的所有诉求，而 Eolink 在软件研发整个生命周期中，做了全方位的补充，从而盘活 API 研发资产。

三、Eolink Apikit 通过 Open API 触发同步操作

本文使用的是 Open API V2 版本，在正式编写代码前，需要先在工作空间管理后台获取调用密钥。

点击在管理后台右上角头像位置的【账号设置】，进入工作空间设置菜单。

解析来我们查看一下通过 Open API 触发同步操作的请求说明：

请求方式：GET
请求参数：
project_id：当前项目的 ID，在【自动生成 API 文档】页面已经自动填充。
space_id：工作空间 ID，同样为 Eolink Apikit 自动生成内容。

有了这些标准之后，我们可以快速通过 Python 编写一个自动触发同步操作的脚本，代码如下。

import requests

url = "https://api.eolink.com/v2/api_studio/【其余内容请在API文档生成页面复制】"

res=requests.get(url

print(res.text

在运行代码前，先对前文的 Python Flask 接口代码进行一下修改，增加【用户来源】字段。然后使用上面的 3 行代码，即可实现自动化同步。上述代码运行结果如下所示。

{"type":"api","status":"success"}

阅读到这里，我们已经实现了【通过 Open API 触发同步操作】，你可以将代码部署到云服务器，并设置成自动任务，这样 Eolink Apikit 就可以实时的抓取服务端 API 文档，解放你的双手了。

四、Eolink Apikit 基于 IDEA 插件上传 API

打开 IDEA 插件，在插件市场搜索 Eolink ApiKit。

接下来就需要对该插件进行配置，参照下图找到 Eolink Settings。

SpaceKey：空间 Key，复制上述域名中的 Key 即可，space-e87yzg；
ProjectHashKey：前文 Open API 中用到的密钥；
Token：你的账号；
StringType：选择第一项即可。

然后在你的项目源码空白处，点击树表右键，选择 Generate Class Doc，一键生成全部 API 注释文档。

五、基于Eolink Apikit API 文档智能生成请求代码和业务代码

前文我们做的所有工作，都是为了让现有 API 文档快速生成并同步到 Eolink Apikit 中，只有这样，我们才能体验 Eolink Apikit 这个一站式 API 生产力工具，盘活 API 研发资产时的强大。

API 文档同步到 Eolink Apikit，一切才刚刚开始！

这部分内置变量和内置函数，学习和使用时可以参考 Eolink Apikit 手册。

//输出信息
eo.info("输出自定义信息";

// 设置http协议url，比如/user/login/admin?user_name={{name}}
eo.http.url.set("http://www.baidu.com";

// MD5 加密
eo.crypt.md5(data;

上述内置函数，搭配上 Eolink Apikit 的 API 自动化测试，可以最大限度的扩展自动化测试需求，真正实现了一键发起测试，一键进行 API 回归测试。

六、总结

在同步的时候，我们可以进行更加详细的配置，扩展如下:

同步接口唯一标识：可选接口标识，接口地址和请求方式，接口名称；
新生成 API 文档状态设置：已发布，设计，待定，开发，测试等；
将发生变更的 API 文档状态设置为：已发布，设计，待定等；
将新生成 API 文档归到指定分组：可选 API 分组目录。

Eolink Apikit 增加了非常详细的同步配置，多方面完善 API 文档更新细节。

编程笔记 » 12年经验的大龄程序员,都用什么写 API 文档