文档自动化|apifox分享
大家都知道接口文档的收益很高，但是编写接口文档可能被认为是耗时且繁琐的任务，而且开发人员可能更愿意专注于实际的编码工作。
文档有时候也有它的主要问题，一般是不准确，并且往往是因为过时了。如果不能一直保持百分百正确的文档是不能被信任的。
文档界诞生了一个活文档的概念，并且有以下四个原则：
- 可靠：无论何时，文档都是准确的，并且与所交付的软件保持同步。
- 省力：最大限度的减少文档的工作量，即使软件发生了变更、删减或者添加，也仅需少量的额外工作。
- 协作：活文档可以促进所有参与者之间的对话和知识共享。
- 有见地：活文档会将人们的注意力引导到工作的各方面，从而提供反馈机会并鼓励深入思考。
今天我想和大家探讨前两点：可靠和省力。
接口文档自动化
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
