wecom openapi

简体中文

描述

该项目旨在将WeCom文档翻译成OpenAPI规范，以便您可以生成各种编程语言的客户端代码。目前，我们使用的是 OpenAPI 规范 3.x 版本。

安装

$ npm install

运行应用程序

当应用程序运行时，将生成OpenAPI规范文件openapi.yaml 。您可以打开http://localhost:3000/openapi查看Swagger UI。

$ npm run start

生成客户端代码

swagger-codegen 是一个非常流行的工具，用于根据 OpenAPI 规范生成代码。但如果你使用 Golang，建议使用 go-swagger。

例子

go-swagge基于OpenAPI规范2.0，因此需要降级版本。

$ npm install -g api-spec-converter
$ api-spec-converter --from=openapi_3 --to=swagger_2 --syntax=yaml --order=alpha ./openapi.yaml > swagger.yaml

然后从swagger.yaml文件生成 Golang 代码。

 $ brew tap go-swagger/go-swagger

$ brew install go-swagger

$ mkdir wecom-api && cd wecom-api

# NOTE: you need run go mod init to create a go.mod file
$ go mod init wecom-api

$ swagger generate client -f swagger.yaml -t wecom-api

开发者

该项目基于NestJS的Swagger集成。详细信息请参考 OpenAPI(NestJS)。

控制器文件中的 API 定义

 nest g --no-spec controller department

创建DTO和响应结构

通常，我们在不同的类中声明 DTO 和 Response。

 nest g --no-spec class department/Department

API属性

  @ApiProperty({
    required: false,
    type: 'string',
    isArray: true,
    maxItems: 100,
    example: '["abel"]',
    description: 'user id list, max length is 100',
  })
  userid_list: string[];

• required ， type为必填。
• description ，推荐example 。

  @ApiOperation({
    operationId: 'getGroupChat',
    summary: 'Get user group detail',
    description: 'Get user group detail',
    externalDocs: {
      url: 'https://developer.work.weixin.qq.com/document/path/92122',
    },
  })

• operationId必需，唯一，是生成代码中的函数名称。
• summary必填
• externalDocs WeCom 官方文档链接。

Swagger UI 尝试一下

授权

首先，您需要获取access_token来授权 api 调用。

代理人

浏览器存在CORS问题，因此我们无法直接访问wx-work。所以我们为您做了一个代理。要访问，请使用http://localhost:3000/cgi-bin 。