简体中文

Description

This project aims to translate the WeCom documentation into OpenAPI Specification, so that you can generate client code in various programming languages. Currently, we are using version 3.x of OpenAPI Specification.

Installation

$ npm install

Running the app

When the app is running, the OpenAPI Specification file openapi.yaml will be generated. You can open http://localhost:3000/openapi to view Swagger UI.

$ npm run start

Generating client code

swagger-codegen is a very popular tool to generate code from OpenAPI Specification. But if you are using Golang, go-swagge is recommended.

Example

go-swagge is based on OpenAPI Specification 2.0, so you need to downgrade the version.

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

Then generate Golang code from swagger.yaml file.

$ 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

Dev

This project is based on Swagger integration of NestJS. Refer to OpenAPI(NestJS) for detail.

API Definition in controller files

nest g --no-spec controller department

Create DTO and Response structure

Usually, we declare DTOs and Responses in different classes.

nest g --no-spec class department/Department

API Properties

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

• required, type is required.
• description, example recommended。

  @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 Required, Unique, Is function name in genertation code.
• summary Required
• externalDocs Link to WeCom official document.

Swagger UI Try it out

Authorize

First, you need to get an access_token to authorize the api calls.

Proxy

Browser has CORS issue, so we cannot access wx-work directly. So we made a proxy for you. To access, use http://localhost:3000/cgi-bin.