{"id":18662119,"url":"https://github.com/liangskyli/routing-controllers-openapi","last_synced_at":"2025-04-11T21:31:39.710Z","repository":{"id":41078530,"uuid":"507325919","full_name":"liangskyli/routing-controllers-openapi","owner":"liangskyli","description":"routing-controllers 生成 openapi v3文件","archived":false,"fork":false,"pushed_at":"2024-12-07T12:52:39.000Z","size":2510,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-25T18:54:00.699Z","etag":null,"topics":["express","koa","openapi3","routing-controllers","swagger"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/liangskyli.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-06-25T14:00:32.000Z","updated_at":"2025-02-27T12:42:10.000Z","dependencies_parsed_at":"2024-01-23T08:28:46.582Z","dependency_job_id":"e55730c7-1294-489c-b78c-32f000e7e77b","html_url":"https://github.com/liangskyli/routing-controllers-openapi","commit_stats":{"total_commits":106,"total_committers":1,"mean_commits":106.0,"dds":0.0,"last_synced_commit":"cc23e0b7d6299842f0292eb2e12721d412ca5a4c"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liangskyli%2Frouting-controllers-openapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liangskyli%2Frouting-controllers-openapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liangskyli%2Frouting-controllers-openapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liangskyli%2Frouting-controllers-openapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/liangskyli","download_url":"https://codeload.github.com/liangskyli/routing-controllers-openapi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247987725,"owners_count":21028975,"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":["express","koa","openapi3","routing-controllers","swagger"],"created_at":"2024-11-07T08:10:01.765Z","updated_at":"2025-04-11T21:31:39.387Z","avatar_url":"https://github.com/liangskyli.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# routing-controllers to openapi 生成工具\n\n\u003cp\u003e\n  \u003ca href=\"https://github.com/liangskyli/routing-controllers-openapi/releases\"\u003e\n    \u003cimg alt=\"preview badge\" src=\"https://img.shields.io/github/v/release/liangskyli/routing-controllers-openapi\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@liangskyli/routing-controllers-openapi\"\u003e\n   \u003cimg alt=\"preview badge\" src=\"https://img.shields.io/npm/v/@liangskyli/routing-controllers-openapi?label=%40liangskyli%2Frouting-controllers-openapi\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n- routing-controllers 生成 openapi v3文件。\n\n## 安装:\n```bash\nyarn add @liangskyli/routing-controllers-openapi --dev\n```\n\n如果项目没有安装prettier，需要安装prettier(^2.0.0 || ^3.0.0)\n```bash\nyarn add prettier --dev\n```\n\n# 生成方式:\n## 1、CLI 命令方式（推荐）\n\n- 默认配置文件在运行目录下openapi.config.ts文件\n\n```bash\nyarn gen-openapi\n```\n\n- 配置文件别名openapi.config2.ts\n\n```bash\nyarn gen-openapi -c ./openapi.config2.ts\n```\n\n### 命令参数\n\n| 参数               | 说明                           | 默认值                 |\n|------------------|------------------------------|---------------------|\n| -c, --configFile | openapi v3文件生成配置文件 `配置参数见下面` | `openapi.config.ts` |\n\n### 命令参数 configFile openapi生成配置文件参数属性\n\n- 类型：IGenOpenapiDataOpts | IGenOpenapiDataOpts[]\n\n### IGenOpenapiDataOpts 参数属性\n\n| 属性                            | 说明                                                                                                                                                      | 默认值                        |\n|-------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------|\n| genOpenapiDir                 | 生成openapi文件夹所在目录                                                                                                                                        | `./`                       |\n| controllers                   | routing-controllers 里的controllers目录                                                                                                                     |                            |\n| prettierOptions               | 生成文件格式化，默认取项目配置，该配置优先级更高，会合并覆盖项目prettier配置文件，如项目有prettier配置文件，这里无需配置，详情配置见 [prettier文档](https://github.com/prettier/prettier/blob/main/docs/options.md) |                            |\n| routingControllersPackageName | routing-controllers包名设置，支持自定义二次封装修改包名                                                                                                                   | `routing-controllers`      |\n| customOmitDecorators          | 忽略警告提示的装饰器                                                                                                                                              | `详见customOmitDecorators属性` |\n| title                         | openapi文件里info=\u003etitle配置  `string`                                                                                                                       | 不设置，取项目package.json里name的值 |\n| routePrefix                   | 全局路由前缀  `string`                                                                                                                                        |                            |\n| compilerOptions               | ts编译参数  `TJS.CompilerOptions`                                                                                                                           | `undefined`                |\n| servers                       | openapi文件里servers配置  `ServerObject[]`                                                                                                                   | `undefined`                |\n| responseSchema                | openapi文件里responses响应数据包裹格式  `ResponseSchema`                                                                                                           | `undefined`                |\n| genOpenapiType                | openapi文件生成格式  `json｜yaml`                                                                                                                              | `json`                     |\n| typeUniqueNames               | 生成类型使用唯一名称  `boolean`                                                                                                                                   | `true`                     |\n\n\n#### customOmitDecorators属性\n\n| 属性      | 说明                                          | 默认值  |\n|---------|---------------------------------------------|------|\n| name    | Decorators名，空字符串适配所有Decorators名    `string` | `./` |\n| package | 包名或路径前缀 `string`                            |      |\n\n- configFile openapi生成配置文件示例\n  - 配置文件支持使用defineConfig定义ts类型\n\n```ts\nimport { defineConfig } from '@liangskyli/routing-controllers-openapi';\n\nexport default defineConfig({\n  genOpenapiDir: './test/all-gen-dirs/gen-openapi-cli-1',\n  controllers: ['./test/example/controller*/**/*.ts'],\n  routePrefix: '/root',\n  // genOpenapiType: 'yaml',\n  // 自定义统一 response 返回结构（可选）\n  responseSchema: {\n    type: 'object',\n    properties: {\n      code: {\n        type: 'number',\n        description: '接口返回code码字段',\n      },\n      data: '#ResponseSchema',\n      msg: {\n        type: 'string',\n        description: '接口返回信息字段',\n      },\n    },\n    required: ['code', 'data'],\n  },\n});\n```\n\n# 生成openapi文件结构指引\n\ngenOpenapiDir下生成的目录结构如下（文件都在openapi文件夹下）：\n\n```bash\n.\n├── openapi // 文件夹\n     ├── openapi-v3.json // openapi v3 json文件\n     └── openapi-v3.yaml // openapi v3 yaml文件\n```\n\n## 2、方法调用方式\n\n### genOpenapiData函数参数\n- 和命令参数configFile属性一致，见上面说明（命令参数 configFile openapi生成配置文件参数属性）。\n- 使用例子\n\n```ts\nimport genOpenapiData from '@liangskyli/routing-controllers-openapi';\n\ngenOpenapiData({\n    title: 'custom title',\n    genOpenapiDir: './test/all-gen-dirs/gen-openapi-cli-1',\n    controllers: ['./test/example/controller*/**/*.ts'],\n    routePrefix: '/root',\n    //genOpenapiType: 'yaml',\n    // 自定义统一 response 返回结构（可选）\n    responseSchema: {\n        type: 'object',\n        properties: {\n            code: {\n                type: 'number',\n                description: '接口返回code码字段',\n            },\n            data: '#ResponseSchema',\n            msg: {\n                type: 'string',\n                description: '接口返回信息字段',\n            },\n        },\n        required: ['code', 'data'],\n    },\n}).then();\n\n```\n\n# routing-controllers 支持项说明\n- 支持的装饰器（其它装饰器不处理）\n  - @Body\n  - @BodyParam\n  - @Controller\n  - @CookieParam\n  - @CookieParams\n  - @Delete\n  - @Get\n  - @Head\n  - @HeaderParam\n  - @HeaderParams\n  - @JsonController\n  - @Param\n  - @Params\n  - @Patch\n  - @Post\n  - @Put\n  - @QueryParam\n  - @QueryParams\n  - @UploadedFile\n  - @UploadedFiles\n- 目前不支持的装饰器支持（会警告提示）\n  - @All\n  - @Authorized\n  - @ContentType\n  - @HttpCode\n  - @Location\n  - @Method\n  - @OnNull\n  - @OnUndefined\n  - @Redirect\n  - @Render\n  - @Req\n  - @Res\n  - @ResponseClassTransformOptions\n- 默认忽略警告提示的装饰器（不会警告提示）\n  - @Ctx\n  - @CurrentUser\n  - @Interceptor\n  - @Header\n  - @Middleware\n  - @Session\n  - @SessionParam\n  - @State\n  - @UseAfter\n  - @UseBefore\n  - @UseInterceptor\n- 使用customOmitDecorators配置忽略警告提示的装饰器\n- 方法需要明确指定入参和返回类型，目前不会对方法返回类型类型进行推导(如下例子)\n  - 类型文件里，同一个文件导出的类型定义名（含命名空间）唯一。请规范声明,不规范的，不生成，警告提示\n- 支持所有的TS类型声明,含namespace的支持（any,never类型会忽略）\n\n# routing-controllers示例\n- [示例](./packages/routing-controllers-openapi/test/example)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fliangskyli%2Frouting-controllers-openapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fliangskyli%2Frouting-controllers-openapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fliangskyli%2Frouting-controllers-openapi/lists"}