{"id":19449219,"url":"https://github.com/juzibot/wecom-openapi","last_synced_at":"2025-04-25T03:31:45.824Z","repository":{"id":38347669,"uuid":"457707390","full_name":"juzibot/wecom-openapi","owner":"juzibot","description":"Swagger OpenAPI of WeCom. 企业微信的 Swagger 文档。","archived":false,"fork":false,"pushed_at":"2022-11-11T03:36:15.000Z","size":1113,"stargazers_count":44,"open_issues_count":0,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-04-17T22:06:00.989Z","etag":null,"topics":["codegen","golang","java","nestjs","nodejs","openapi","openapi3","qychat","qywork","qywx","swagger","typescript","wechat","wecom","wework","workweixin","workwx","wxwork"],"latest_commit_sha":null,"homepage":"https://wecom-openapi.juzibot.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/juzibot.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-02-10T09:13:32.000Z","updated_at":"2023-09-11T09:04:50.000Z","dependencies_parsed_at":"2023-01-21T22:47:18.605Z","dependency_job_id":null,"html_url":"https://github.com/juzibot/wecom-openapi","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juzibot%2Fwecom-openapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juzibot%2Fwecom-openapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juzibot%2Fwecom-openapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juzibot%2Fwecom-openapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/juzibot","download_url":"https://codeload.github.com/juzibot/wecom-openapi/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223979423,"owners_count":17235395,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["codegen","golang","java","nestjs","nodejs","openapi","openapi3","qychat","qywork","qywx","swagger","typescript","wechat","wecom","wework","workweixin","workwx","wxwork"],"created_at":"2024-11-10T16:31:01.994Z","updated_at":"2024-11-10T16:32:35.073Z","avatar_url":"https://github.com/juzibot.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"https://wwcdn.weixin.qq.com/node/wework/images/logo.c768c756ab.png\" width=\"300\"\u003e\n\u003cimg src=\"https://www.openapis.org/wp-content/uploads/sites/3/2018/02/OpenAPI_Logo_Pantone-1.png\" width=\"300\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/swagger-api/swagger.io/wordpress/images/assets/SWU-logo-clr.png\" width=\"300\"\u003e\n\n#\n\n[简体中文](./README_ZH.md)\n\n## Description\n\nThis 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.\n\n## Installation\n\n```bash\n$ npm install\n```\n\n## Running the app\n\nWhen the app is running, the OpenAPI Specification file `openapi.yaml` will be generated. You can open `http://localhost:3000/openapi` to view Swagger UI.\n\n```bash\n$ npm run start\n```\n\n## Generating client code\n\n[swagger-codegen](https://github.com/swagger-api/swagger-codegen) is a very popular tool to generate code from OpenAPI Specification. But if you are using Golang, [go-swagge](https://github.com/go-swagger/go-swagger) is recommended.\n\n### Example\n\n[go-swagge](https://github.com/go-swagger/go-swagger) is based on OpenAPI Specification 2.0, so you\nneed to downgrade the version.\n\n```bash\n$ npm install -g api-spec-converter\n$ api-spec-converter --from=openapi_3 --to=swagger_2 --syntax=yaml --order=alpha ./openapi.yaml \u003e swagger.yaml\n```\n\nThen generate Golang code from `swagger.yaml` file.\n\n```\n$ brew tap go-swagger/go-swagger\n\n$ brew install go-swagger\n\n$ mkdir wecom-api \u0026\u0026 cd wecom-api\n\n# NOTE: you need run go mod init to create a go.mod file\n$ go mod init wecom-api\n\n$ swagger generate client -f swagger.yaml -t wecom-api\n```\n\n## Dev\n\nThis project is based on Swagger integration of NestJS. Refer to [OpenAPI(NestJS)](https://docs.nestjs.com/openapi/introduction) for detail.\n\n### API Definition in controller files\n\n```\nnest g --no-spec controller department\n```\n\n### Create DTO and Response structure\n\nUsually, we declare DTOs and Responses in different classes.\n\n```\nnest g --no-spec class department/Department\n```\n\n### API Properties\n\n```\n  @ApiProperty({\n    required: false,\n    type: 'string',\n    isArray: true,\n    maxItems: 100,\n    example: '[\"abel\"]',\n    description: 'user id list, max length is 100',\n  })\n  userid_list: string[];\n```\n\n- `required`, `type` is required.\n- `description`, `example` recommended。\n\n```\n  @ApiOperation({\n    operationId: 'getGroupChat',\n    summary: 'Get user group detail',\n    description: 'Get user group detail',\n    externalDocs: {\n      url: 'https://developer.work.weixin.qq.com/document/path/92122',\n    },\n  })\n```\n\n- `operationId` Required, Unique, Is function name in genertation code.\n- `summary` Required\n- `externalDocs` Link to WeCom official document.\n\n## Swagger UI Try it out\n\n### Authorize\n\nFirst, you need to get an `access_token` to authorize the api calls.\n![](./screenshot/authorize_step.png)\n\n### Proxy\n\nBrowser 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`.\n![](./screenshot/proxy_step.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjuzibot%2Fwecom-openapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjuzibot%2Fwecom-openapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjuzibot%2Fwecom-openapi/lists"}