Posts

文档自动化|apifox分享

brian

2024年1月15日 — 5 min read

大家都知道接口文档的收益很高，但是编写接口文档可能被认为是耗时且繁琐的任务，而且开发人员可能更愿意专注于实际的编码工作。

文档有时候也有它的主要问题，一般是不准确，并且往往是因为过时了。如果不能一直保持百分百正确的文档是不能被信任的。

文档界诞生了一个活文档的概念，并且有以下四个原则：

可靠：无论何时，文档都是准确的，并且与所交付的软件保持同步。
省力：最大限度的减少文档的工作量，即使软件发生了变更、删减或者添加，也仅需少量的额外工作。
协作：活文档可以促进所有参与者之间的对话和知识共享。
有见地：活文档会将人们的注意力引导到工作的各方面，从而提供反馈机会并鼓励深入思考。

今天我想和大家探讨前两点：可靠和省力。

接口文档自动化

protobuffer + protoc 插件 + openapi ，我认为是这一个“银弹”。

我们可以使用 proto 原型文件 + 插件 protoc-gen-gin-http 生成接入层的接口路由代码。还可以使用 proto 原型文件 + 插件 protoc-gen-openapi 生成 openapi 文件。

Proto 原型文件示例

syntax = "proto3";

package post;

import "post/post_data.proto";
import "post/common.proto";
import "google/protobuf/struct.proto";

option go_package = "codeup.aliyun.com/brian/api/post";

service Free {

    // GameReward视频
    rpc GetGameReward (RewardRequest) returns (RewardReply) {
      option (google.api.http) = {
        get: "/v1/game/reward/index",
      };
    }
        
    // 激励视频相关
    // 包含客户端接口和 h5 接口
    message RewardRequest {
      // 广告id
      string ad_id = 1;
      // 用户安装天数(0:<24小时 | 1:24-48小时 | -1:大于7天)
      string user_activate_day = 2;
      // 性别(0:不区分性别 | 1:男生 | 2:女生)
    }
    
    message RewardReply {
      RewardRequest params = 1;
    }
    
}

Makefile 示例


doc:  # 接口文档生成
    protoc --proto_path=./api \
       --proto_path=./third_party \
       --proto_path=./docs \
       --openapi_out=fq_schema_naming=true,naming=proto,default_response=false:. \
       $(API_PROTO_FILES) docs/api_readme.proto

执行 make doc，即可生成文档 openapi.yaml 到根目录有了 openapi.yaml 文件，导入任意一个支持 openapi 的文档平台，都能实现接口文档自动化。碰巧 apifox 就支持。

解决的问题

可靠：文档的来源是“权威”的，它来自代码，代码是最“权威”的文档。
胜利：自动化，保证内容不过时，同时降低开发人员的负担。

apifox 使用技巧

导入

我们执行 make api 可以生产 openapi.yaml 文件之后，就可以导入到 apifox 了。导入有3种方式分为：手动导入、定时导入、api导入一般不建议使用手动导入，每次都要选择文件。建议使用定时导入，开发团队中每个人配置好 openapi.yaml 文件路径，关闭启用，开发过程中可点击立即导入 实现快速导入。

** 有可能不同的人在同一个项目中的不同分支，开发同一个接口，如担心接口文档互相覆盖，那么我们可以在导入的设置中选择 智能合并。

API导入

apifox 提供了上传接口，可以在生成 openapi.yaml 文件之后，直接导入到 apifox。

🔗文档：https://apifox-openapi.apifox.cn/

但是商业化还未采用使用调用API导入的这种方式，我认为做到手动执行配置导入，已经能打 90 分了。

创建项目级别文档说明

我们可以为一个项目创建文档，说明项目概况，格式的定义，比如接口统一的 header 参数。

Apifox 可以创建文档，支持 Markdown。接口项目级文档。

但，我可能不会这么做。

保证文档可靠有一个准则：尽量使用单一来源发布机制。所以针对此类文档，我可能建议专门在 proto 中编写一个无意义的接口，然后添加详细的说明。比如：商业化使用 GET /README 作为项目级别的文档。

文档分享

3.1 自定义分享

客户端和前端可以使用 apifox 软件，也可以访问通过分享功能创建的网页文档。在线分享 - 自定义分享 - 分享列表。网页文档不能使用设置团队访问权限，只能公开访问或加密码访问。公司的 Apifox 是独立部署，已经设置了仅公司内网可访问，所以问题不大。如果考虑安全级别较高，建议大家使用 apifox 软件访问。

3.2 发布文档

全公司公开的项目，还可以选择发布到 APIHUB。发布之后，可以在主页 - API hub 查看。

接口调用

我们一般会有很多测试环境，切换测试环境可以 host 总归会有些麻烦。我们知道 curl 是可以指定 ip 访问的。

curl --location -g --request GET 'http://127.0.0.1/v1/adv/index' \
--header 'Host: api.demo.com'

那么我们就可以通过这个特性完成区分环境的调用。Http 接口请求，前置 URL 使用 IP，环境 HOST。

Grpc 导入

proto 文件

参考：

google api https://pkg.go.dev/github.com/gogo/googleapis/google/api#hdr-gRPC_Transcoding