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

写代码，程序员不害怕。

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

为什么？

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

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

首先，要易用且提供文档编写工具和模板，可以更容易地编写和组织文档，节省时间和精力。此外，还要提供自动生成文档的功能，无需手动编写和格式化文档，可以更快地生成文档。

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

我们围绕【智能生成+盘活 API 资产】，深度 “盘” 一下 Eolink Apikit 这款 API 工具。

重点围绕产研需求展开：

当 API 代码更新之后，API 文档自动刷新

API 协作工具通过脚本进行自动刷新/同步

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

一、Python 快速搭建 Swagger

在对接 API 工具前，需要先用 Python Flask 框架在本地构建一个微型项目，用于写接口代码。我比较习惯的 Web API 框架是 Flask，所以搭建 Swagger 需要用到 Flasgger 模块，如果你用 FastAPI，可以不用多走这一步，直接使用 FastAPI 原生 API 文档即可。

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

首先安装 flasgger 模块。

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 文档之后，对比差异。

作为一名合格的软件研发工程师，在公司团队协作开发的时候，一定要遵守团队 API 文档规范，边写代码，边写注释，边写文档。

在上述界面中，找到 appispec_1.json 超链接位置，点击该链接，页面跳转到 Swagger 生成的 JSON 文件地址，如下所示。

http://127.0.0.1:5000/apispec_1.json

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

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

在前文拿到 JSON 文件地址后，就可以在 Eolink Apikit 读取该网络文件，并自动生成 API 文档页面了，具体操作如下。

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

进入到【自动生成 API 文档】功能页之后，选择【添加来源】按钮。

在弹窗中选择通过 Swagger URL 生成 API 文档，点击下一步：

在【添加来源】弹窗输入 Swagger 生成的 JSON 文件地址，就是刚刚得到的 JSON 文件地址，这里一定要注意，该地址能通过外网访问（因为 Eolink Apikit 服务器不能调用我们本地的数据），并且为 JSON 格式（刚刚已经核对过目标数据），然后参考下图进行填写。

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

互联网公司项目，文档一般是支持外网访问的，这个问题只会在我们学习阶段碰到。

注意：上图右侧【完善配置】所有数据保持默认即可。

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

点击同步按钮，将 Swagger 文件内容同步到 Eolink Apikit 中。

再次切换到 API 列表页面，可以看到 API 同步之后的效果。

此时打开任意 API 文档，可以查看到 API 描述，请求地址，请求参数，返回参数等其它信息，到这里 Eolink Apikit 已经成功进行同步。

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

这里咱们需要做一个小小的总结：在公司团队协作的场景下，经常出现文档和代码不同步情况，所以我们引入了 Swagger 模块，让小组中的程序员，在编写代码的同时，只需要更新自己的代码和注释，即可自动生成 API 文档。

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

除了手动点击【同步】操作外，我们还可以通过 Open API 实现自动同步。

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

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

密钥配置

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

切换的页面中，选择【Open API】，进入密钥配置。

为了数据安全，请不要将密钥泄露。点击上图箭头指向位置，查看密钥明细，直接点击即可复制。

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

请求协议：HTTPS
请求方式：GET
请求地址：https://api.eolink.com/v2/api_studio/management/api/auto_scan
请求参数：
- eo_secret_key：open api 的访问鉴权密钥，前文刚刚复制的字符串。
- project_id：当前项目的 ID，在【自动生成 API 文档】页面已经自动填充。
- space_id：工作空间 ID，同样为 Eolink Apikit 自动生成内容。
请求响应
- 数据请求成功，返回 JSON 格式数据，

有了这些标准之后，我们可以快速通过 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

Eolink Apikit 除了手动同步和以 Open API 形式同步文档以外，还可以通过 IDEA 插件实现快速在研发工具上操作并上传 API 接口文档，而且比 Swagger 的方式还快，具体步骤如下所示。

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

点击上图的 Install 即可安装。

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

看一下 Eolink Settings 中的相关参数配置。

Server：这里使用域名+/api 格式，例如橡皮擦的是 https://space-e87yzg.w.eolink.com/api；
SpaceKey：空间 Key，复制上述域名中的 Key 即可，space-e87yzg；
ProjectHashKey：前文 Open API 中用到的密钥；
Token：你的账号；
StringType：选择第一项即可。

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

生成完毕，再次选择 Upload All Api 即可上传所有 API 注释到目标服务器，真正的一键生成文档，一键上传文档，如果你恰好使用的是 IDEA ，一定要尝试一下该方式，在 Eolink Apikit 的帮助下，写文档会变成一件非常轻松的事。

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

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

下面将借助刚刚建立的接口，为大家展示 Eolink Apikit API 智能生成请求代码和业务代码这一重点功能，过程中还将为大家介绍 Eolink Apikit 的一些小细节亮点。

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

选择进入前文同步的任意接口中，可以得到该接口的详细描述，更多内容可在你的 Eolink Apikit 后台查看，这里仅展示局部。

如果你善于发现，一定会发现一个非常不起眼的按钮 —【生成预览数据】，点击它。这个操作非常适合测试工程师进行数据模拟，尤其是当 API 接口包含大量参数待填写时，可以大幅度节约手写参数的消耗时间，而且测试的时候，可以避免使用 abc，aaa，1111，123，这些 “左手乱敲” 的输入数据。

然后我们再看一个强大的功能，生成请求代码和业务代码，你可以借助 Eolink Apikit 生成指定 API 的各语言调用代码，操作非常便捷，只需要点击 API 文档详情页右上角 “代码示例” 图标即可。

在弹出的抽屉页中，可以选择你需要的代码示例，这里依据实战应用场景进行选择，例如橡皮擦需要的是 NodeJS 代码，选择对应语言类型之后，可以得到下图所示内容，下载脚本即可用于请求代码和业务代码。

最后，我们在补充一个 Eolink Apikit 的亮点功能，Eolink Apikit 可以直接发起 API 测试，并且可以在接口前后增加前置脚本和后置脚本，二者的原理是在 API 执行前/后执行 Javascript 脚本，从而改变请求参数或者进行签名加密等操作。

这部分内置变量和内置函数，学习和使用时可以参考 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 回归测试。

六、总结

我们从 Eolink Apikit 与 Python Flask Swagger 文件打通开始，为大家介绍了两种 Eolink Apikit 同步 API 文档的方法，实战中还是建议大家在服务器端部署 Open API 同步脚本，自动化实现 Swagger 和 Eolink Apikit 同步。

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

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

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