句子互动技术团队针对企业微信开发文档做了基于 OpenAPI Specification 的翻译工作，使得开发者可以使用命令一键生成对应编程语言的代码，零成本对接企业微信的 API。
为什么会有这个项目
企业微信开放了大量的 API 接口，使得企业和服务商可以自定义开发配套应用提高企业微信的使用效率。但繁多的 API 和参数配置，使得开发者的使用成本很高，尤其当需要实现多种编程语言的版本时。
句子互动技术团队基于 OpenAPI 规范对企业微信开发文档做了翻译工作，使得开发者可以使用命令直接生成对应编程语言的代码，零成本对接企业微信的 API。
关于 OpenAPI 规范
OpenAPI Specification（OAS）定义了一个标准的、语言无关的 RESTful API 接口规范，它可以同时允许开发人员和计算机查看并理解某个服务的功能，而无需访问源代码、文档或网络流量检查，既方便人类学习和阅读，也方便机器阅读。正确定义 OAS 后，开发者可以使用最少的实现逻辑来理解远程服务并与之交互。
此外，文档生成工具可以使用 OpenAPI 规范来生成 API 文档，代码生成工具可以生成各种编程语言下的服务端和客户端代码，测试代码和其他用例。详见：OpenAPI Specification
WeCom-OpenAPI 项目
句子互动技术团队基于 AOS 对企业微信开发文档做了翻译，并上线了 Wecom-OpenAPI 项目。
WeCom-OpenAPI 是利用 NestJS 的 Swagger 集成能力来实现的，@nestjs/swagger 提供了一些里的装饰器（Decorators）来声明 Swagger 属性，方便管理 API 之间的关联关系。
如何使用
Wecom-OpenAPI 项目已在 GitHub 完全开源(点击这里查看)。
把代码 clone 到本地，安装依赖后启动项目。启动后会在根目录生成 swagger spec 文件 openapi.yaml。
在浏览器打开http://localhost:3000/openapi 可查看 Swagger UI。
$ git clone git@github.com:juzibot/wecom-openapi.git
$ cd wecom-opwenapi && npm install
$ npm run startWeCom-OpenAPI 提供了对企业微信 API 的代理转发，所以你可以在 Swagger UI 上直接对 API 进行调试。首先将你的 AccessToken 配置好。
然后选择本地代理地址即可，这样就不会出现跨域的问题。
代码生成
主流的代码生成工具是 swagger-codegen，但是它生成的 golang 代码不太友好，所以这里推荐使用 go-swagger 项目，但是目前只支持 swagger 2.0 版本，所以需要将上面得到的 openapi.yaml 文件转换成一下版本。这里使用 api-spec-converter 来做版本转换。
$ npm install -g api-spec-converter
# 转换文档版本
$ api-spec-converter --from=openapi_3 --to=swagger_2 \
--syntax=yaml \
--order=alpha \
./openapi.yaml > swagger.yaml
# 安装 go-swaager
$ brew install go-swagger
$ mkdir wecom-api
# 生成 golang 代码，要求目标目录必须在 GO_PATH 中
$ cd wecom-api && go mod init wecom-api
# 生成 golang 代码
$ swagger generate client -f swagger.yaml -t wecom-api至此，在 wecom-api 目录中会得到生成的代码文件
./wecom-api/
├── client
└── models
- client 目录中存放 Client 对象和 Parameter、Response 包装对象
- models 目录存放 Dto、Response 的实体定义
Example
package main
import (
"log"
"wecom-api/client"
"wecom-api/client/department"
"github.com/go-openapi/runtime"
"github.com/go-openapi/strfmt"
)
// 定义鉴权对象
type auth struct{}
var token = "token"
// 实现 ClientAuthInfoWriter 接口
func (a *auth) AuthenticateRequest(req runtime.ClientRequest, reg strfmt.Registry) error {
// 将 token 放在正确的位置
return req.SetQueryParam("access_token", token)
}
func main() {
departmentID := float64(1)
params := department.NewListDepartmentParams()
params.SetID(&departmentID)
resp, err := client.Default.Department.ListDepartment(params, &auth{})
if err != nil {
log.Fatalf("err: %v", err)
}
log.Printf("%v, %s", resp.Payload.Errcode, resp.Payload.Errmsg)
for _, v := range resp.Payload.Department {
log.Printf("%v", v)
}
}更多 Wecom-OpenAPI
我们已经将此项目部署在了句子互动官网，你可以复制地址wecom-openapi.juzibot.com 在浏览器打开直接使用。
句子互动技术团队已经完成了常用接口文档的翻译工作，但仍有许多接口的翻译等待被完成，如果你有兴趣和精力参与共建，我们非常欢迎你的加入。
你可以直接在 GitHub 中提交 PR，也可以扫描下方二维码进入我们的 Contributor 社群一起讨论~
