{"id":15091454,"url":"https://github.com/e22m4u/ts-openapi","last_synced_at":"2025-04-12T07:11:12.640Z","repository":{"id":236377706,"uuid":"792509962","full_name":"e22m4u/ts-openapi","owner":"e22m4u","description":"TypeScript decorators for generating The OpenAPI Document","archived":false,"fork":false,"pushed_at":"2025-02-19T10:19:26.000Z","size":87,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-26T02:22:57.660Z","etag":null,"topics":["decorator","documentation","esm","generator","openapi","swagger","typescript"],"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/e22m4u.png","metadata":{"files":{"readme":"README-ru.md","changelog":null,"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":"2024-04-26T20:25:30.000Z","updated_at":"2025-02-19T10:19:30.000Z","dependencies_parsed_at":"2025-01-05T22:21:08.723Z","dependency_job_id":"004ea970-fdef-4312-bf52-7f7a42bdcfea","html_url":"https://github.com/e22m4u/ts-openapi","commit_stats":{"total_commits":39,"total_committers":1,"mean_commits":39.0,"dds":0.0,"last_synced_commit":"763f5423ab9213f7759ee600a7c8d6918de29eec"},"previous_names":["e22m4u/ts-openapi"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e22m4u%2Fts-openapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e22m4u%2Fts-openapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e22m4u%2Fts-openapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e22m4u%2Fts-openapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/e22m4u","download_url":"https://codeload.github.com/e22m4u/ts-openapi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248530575,"owners_count":21119600,"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":["decorator","documentation","esm","generator","openapi","swagger","typescript"],"created_at":"2024-09-25T10:41:12.446Z","updated_at":"2025-04-12T07:11:12.630Z","avatar_url":"https://github.com/e22m4u.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"## @e22m4u/ts-openapi\n\n*[English](./README.md) | Русский*\n\nНабор TypeScript декораторов для генерации\n[OpenAPI Документа 3.1.0](https://spec.openapis.org/oas/v3.1.0)\n\n## Установка\n\n```bash\nnpm install @e22m4u/ts-openapi\n```\n\n#### Поддержка декораторов\n\nДля включения поддержки декораторов, добавьте указанные\nниже опции в файл `tsconfig.json` вашего проекта.\n\n```json\n{\n  \"emitDecoratorMetadata\": true,\n  \"experimentalDecorators\": true\n}\n```\n\n## Пример\n\nОписание операций контроллера с помощью [декораторов](#Декораторы)\nкласса, методов и параметров.\n\n```ts\nimport {\n  oaTag,\n  oaResponse,\n  oaOperation,\n  oaParameter,\n  oaRequestBody,\n} from '@e22m4u/ts-openapi';\n\nimport {\n  OADataType,\n  OAMediaType,\n  OAOperationMethod,\n  OAParameterLocation,\n} from '@e22m4u/ts-openapi';\n\ntype User = {\n  id: number,\n  name: string,\n  email: string,\n}\n\n@oaTag({\n  name: 'User',\n  path: '/user',\n})\nclass UserController {\n  @oaOperation({\n    method: OAOperationMethod.PATCH,\n    path: '/{id}',\n  })\n  @oaResponse({\n    mediaType: OAMediaType.JSON,\n    description: 'Patched User',\n    schema: {\n      type: OADataType.OBJECT,\n      properties: {\n        id: {type: OADataType.NUMBER},\n        name: {type: OADataType.STRING},\n        email: {type: OADataType.STRING},\n      },\n    },\n  })\n  patchById(\n    @oaParameter({\n      name: 'id',\n      in: OAParameterLocation.PATH,\n      schema: {type: OADataType.NUMBER},\n    })\n    id: string,\n    @oaRequestBody({\n      mediaType: OAMediaType.JSON,\n      schema: {\n        type: OADataType.OBJECT,\n        properties: {\n          name: {type: OADataType.STRING},\n          email: {type: OADataType.STRING},\n        },\n      },\n    })\n    body: User,\n  ): User {\n    // ...\n  }\n}\n```\n\nГенерация OpenApi документа используя класс контроллера\nс размеченными мета-данными.\n\n```ts\nimport {OADocumentBuilder} from '@e22m4u/ts-openapi';\n\nconst builder = new OADocumentBuilder({info: {title: 'My project'}});\nbuilder.useClassMetadata(UserController);\nconst doc = builder.build();\n\nconsole.log(doc);\n```\n\nРезультат работы метода `build` класса `OADocumentBuilder`\n\n```json\n{\n  \"openapi\": \"3.1.0\",\n  \"info\": {\n    \"title\": \"My project\"\n  },\n  \"tags\": [\n    {\n      \"name\": \"User\"\n    }\n  ],\n  \"paths\": {\n    \"/user/{id}\": {\n      \"patch\": {\n        \"tags\": [\n          \"User\"\n        ],\n        \"parameters\": [\n          {\n            \"name\": \"id\",\n            \"in\": \"path\",\n            \"schema\": {\n              \"type\": \"number\"\n            }\n          }\n        ],\n        \"requestBody\": {\n          \"content\": {\n            \"application/json\": {\n              \"schema\": {\n                \"type\": \"object\",\n                \"properties\": {\n                  \"name\": {\n                    \"type\": \"string\"\n                  },\n                  \"email\": {\n                    \"type\": \"string\"\n                  }\n                }\n              }\n            }\n          }\n        },\n        \"responses\": {\n          \"default\": {\n            \"description\": \"Patched User\",\n            \"content\": {\n              \"application/json\": {\n                \"schema\": {\n                  \"type\": \"object\",\n                  \"properties\": {\n                    \"id\": {\n                      \"type\": \"number\"\n                    },\n                    \"name\": {\n                      \"type\": \"string\"\n                    },\n                    \"email\": {\n                      \"type\": \"string\"\n                    }\n                  }\n                }\n              }\n            }\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n## Декораторы\n\n### @oaTag\n\nОписывает группу операций контроллера.\n\n```ts\nimport {oaTag} from '@e22m4u/ts-openapi';\n\n@oaTag({\n  name: 'User',\n  description: 'The User Controller',\n  // параметр \"path\" используется как\n  // префикс маршрута для операций\n  // данного контроллера\n  path: '/user',\n})\nclass UserController {/* ... */}\n```\n\n[OATagMetadata.ts](src/decorators/tag/tag-metadata.ts)\n\nСпецификация:\n- [Tag Object](https://spec.openapis.org/oas/v3.1.0#tag-object)\n\n### @oaOperation\n\nОписывает операцию определенного маршрута.\n\n```ts\nimport {\n  oaOperation,\n  OAOperationMethod,\n} from '@e22m4u/ts-openapi';\n\nclass UserController {\n  @oaOperation({\n    method: OAOperationMethod.GET,\n    path: '/users/{id}',\n    summary: 'Find by the given id',\n    description: 'Returns a model',\n    // ...\n  })\n  findById() {/* ... */}\n}\n```\n\n[OAOperationMetadata.ts](/src/decorators/operation/operation-metadata.ts)\n\nСпецификация:\n- [Paths Object](https://spec.openapis.org/oas/v3.1.0#paths-object)  \n- [Path Item Object](https://spec.openapis.org/oas/v3.1.0#path-item-object)  \n- [Operation Object](https://spec.openapis.org/oas/v3.1.0#operation-object)\n\n### @oaResponse\n\nОписывает возвращаемый ответ операции.\n\n```ts\nimport {\n  oaResponse,\n  OADataType,\n  OAMediaType,\n} from '@e22m4u/ts-openapi';\n\nclass UserController {\n  @oaResponse({\n    statusCode: 200,\n    mediaType: OAMediaType.JSON,\n    description: 'Response description',\n    schema: {\n      type: OADataType.OBJECT,\n      parameters: {\n        id: {type: OADataType.NUMBER},\n        name: {type: OADataType.STRING},\n      },\n    },\n    example: {\n      id: 10,\n      name: 'John Doe',\n    },\n    // ...\n  })\n  findById() {/* ... */}\n}\n```\n\n[OAResponseMetadata.ts](src/decorators/response/response-metadata.ts)\n\nСпецификация:\n- [Responses Object](https://spec.openapis.org/oas/v3.1.0#responses-object)  \n- [Response Object](https://spec.openapis.org/oas/v3.1.0#response-object)  \n- [Schema Object](https://spec.openapis.org/oas/v3.1.0#schema-object)\n\n### @oaParameter\n\nОписывает параметр операции.\n\n```ts\nimport {\n  OADataType,\n  oaParameter,\n  OAParameterLocation,\n} from '@e22m4u/ts-openapi';\n\nclass UserController {\n  // декоратор параметра можно\n  // применить к методу\n  @oaParameter({\n    name: 'foo',\n    in: OAParameterLocation.QUERY,\n    schema: {type: OADataType.STRING},\n  })\n  findById(\n    // или непосредственно\n    // к нужному параметру\n    @oaParameter({\n      name: 'bar',\n      in: OAParameterLocation.QUERY,\n      schema: {type: OADataType.STRING},\n    })\n    bar: number,\n  ) {/* ... */}\n}\n```\n\n[OAParameterMetadata.ts](src/decorators/parameter/parameter-metadata.ts)\n\nСпецификация:\n- [Parameter Object](https://spec.openapis.org/oas/v3.1.0#parameter-object)  \n- [Schema Object](https://spec.openapis.org/oas/v3.1.0#schema-object)\n\n### @oaRequestBody\n\nОписывает тело принимаемого запроса.\n\n```ts\nimport {\n  OADataType,\n  OAMediaType,\n  oaRequestBody,\n} from '@e22m4u/ts-openapi';\n\nclass UserController {\n  // декоратор тела запроса\n  // можно применить к методу\n  @oaRequestBody({\n    mediaType: OAMediaType.JSON,\n    schema: {\n      type: OADataType.OBJECT,\n      properties: {\n        name: {type: OADataType.STRING},\n        email: {type: OADataType.STRING},\n      },\n    },\n  })\n  create(\n    // или непосредственно\n    // к нужному параметру\n    @oaRequestBody({\n      mediaType: OAMediaType.JSON,\n      schema: {\n        type: OADataType.OBJECT,\n        properties: {\n          name: {type: OADataType.STRING},\n          email: {type: OADataType.STRING},\n        },\n      },\n    })\n    body: object,\n  ) {/* ... */}\n}\n```\n\n[OARequestBodyMetadata.ts](src/decorators/request-body/request-body-metadata.ts)\n\nСпецификация:\n- [Request Body Object](https://spec.openapis.org/oas/v3.1.0#request-body-object)\n\n## Тесты\n\n```bash\nnpm run test\n```\n\n## Лицензия\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fe22m4u%2Fts-openapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fe22m4u%2Fts-openapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fe22m4u%2Fts-openapi/lists"}