wecom openapi

简体中文

Descrição

Este projeto tem como objetivo traduzir a documentação do WeCom para a especificação OpenAPI, para que seja possível gerar código cliente em diversas linguagens de programação. Atualmente, estamos usando a versão 3.x da especificação OpenAPI.

Instalação

$ npm install

Executando o aplicativo

Quando o aplicativo estiver em execução, o arquivo de especificação OpenAPI openapi.yaml será gerado. Você pode abrir http://localhost:3000/openapi para visualizar a UI do Swagger.

$ npm run start

Gerando código do cliente

swagger-codegen é uma ferramenta muito popular para gerar código a partir da especificação OpenAPI. Mas se você estiver usando Golang, recomenda-se go-swagge.

Exemplo

go-swagge é baseado na especificação OpenAPI 2.0, então você precisa fazer downgrade da versão.

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

Em seguida, gere o código Golang do arquivo swagger.yaml .

 $ 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

Desenvolvedor

Este projeto é baseado na integração Swagger do NestJS. Consulte OpenAPI (NestJS) para obter detalhes.

Definição de API em arquivos de controlador

 nest g --no-spec controller department

Criar DTO e estrutura de resposta

Normalmente declaramos DTOs e Respostas em classes diferentes.

 nest g --no-spec class department/Department

Propriedades da 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 é obrigatório.
• description , example recomendado。

  @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 Obrigatório, Único, É o nome da função no código de geração.
• summary Obrigatório
• externalDocs Link para documento oficial da WeCom.

UI Swagger Experimente

Autorizar

Primeiro, você precisa obter um access_token para autorizar as chamadas da API.

Procurador

O navegador tem problema de CORS, portanto não podemos acessar o wx-work diretamente. Então fizemos um proxy para você. Para acessar, use http://localhost:3000/cgi-bin .