{"id":18943099,"url":"https://github.com/kimyu0218/swagger-decorator-builder","last_synced_at":"2026-03-25T02:30:18.220Z","repository":{"id":213220588,"uuid":"733348832","full_name":"kimyu0218/swagger-decorator-builder","owner":"kimyu0218","description":"Decorator Builder for Swagger","archived":false,"fork":false,"pushed_at":"2024-01-14T10:40:58.000Z","size":198,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-12-31T23:42:23.233Z","etag":null,"topics":["custom-decorators","swagger","swagger-api","swagger-decorators"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@kimyu0218/swagger-decorator-builder","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/kimyu0218.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-12-19T06:02:31.000Z","updated_at":"2024-01-13T07:04:32.000Z","dependencies_parsed_at":"2023-12-22T19:24:39.681Z","dependency_job_id":"bd334ea0-528f-4a68-a1b3-0c5473a959b3","html_url":"https://github.com/kimyu0218/swagger-decorator-builder","commit_stats":null,"previous_names":["kimyu0218/swagger-decorator-builder"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kimyu0218%2Fswagger-decorator-builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kimyu0218%2Fswagger-decorator-builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kimyu0218%2Fswagger-decorator-builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kimyu0218%2Fswagger-decorator-builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kimyu0218","download_url":"https://codeload.github.com/kimyu0218/swagger-decorator-builder/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239942793,"owners_count":19722336,"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":["custom-decorators","swagger","swagger-api","swagger-decorators"],"created_at":"2024-11-08T12:40:29.035Z","updated_at":"2026-03-25T02:30:18.174Z","avatar_url":"https://github.com/kimyu0218.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Swagger Decorator Builder 🛠️\n\n![npm](https://img.shields.io/npm/v/@kimyu0218/swagger-decorator-builder) ![npm](https://img.shields.io/npm/dt/@kimyu0218/swagger-decorator-builder)\n\n\u003cbr\u003e\n\n### Installation ⬇️\n\n```bash\nnpm i @kimyu0218/swagger-decorator-builder\n```\n\n\u003cbr\u003e\n\n### Introduction 👀\n\nThis project is a Swagger Decorator Builder designed to **simplify the creation of Swagger decorators for API documentation**.\n\nThe existing Swagger decorators often result in lengthy code, impacting readability. In response to this issue, I initiated this project to create custom decorators using a **builder pattern**, aiming for more concise and efficient decorator composition.\n\n```ts\nexport const FindAllCatsDecorator = (target: string, returnType: any) =\u003e\n  new SwaggerDecoratorBuilder(target, 'GET', returnType) // Automatically set API operation summary. (target: 'cats' -\u003e GET cats)\n    .removeResponse(401) // Remove the default 401 API response.\n    .removeResponse(403) // Remove the default 403 API response.\n    .removeResponse(404) // Remove the default 404 API response.\n    .build();\n\nexport const UpdateCatDecorator = (\n  target: string,\n  param: ApiParamOptions,\n  body: ApiBodyOptions,\n) =\u003e\n  new SwaggerDecoratorBuilder(target, 'PATCH') // Automatically set API operation summary. (target: 'cat' -\u003e PATCH cat)\n    .addParam(param) // Set the request param.\n    .setBody(body) // Set the request body.\n    .addResponse({ status: 403, description: 'Forbidden - Unauthorized User' }) // Overwrite the default 403 API response.\n    .build();\n```\n\n\u003cbr\u003e\n\n### How to Use ❓\n\n1. Import `SwaggerDecoratorBuilder` class.\n\n```ts\nimport { SwaggerDecoratorBuilder } from '@kimyu0218/swagger-decorator-builder';\n```\n\n2. Pass `target`, `method` parameters to the constructor. The builder will automatically create a summary of `@ApiOperation()` decorator. If you want to put a `returnType` in `@ApiOkResponse()`, you can optionally hand over the `returnType`!\n\n```ts\nnew SwaggerDecoratorBuilder(target, 'GET', returnType) ...\n```\n\n3. If needed, use the `addParam` and `setBody` methods to add `@ApiParam()` and `@ApiBody()` decorators.\n\n```ts\nnew SwaggerDecoratorBuilder(target, 'PATCH').addParam(param).setBody(body) ...\n```\n\n4. Use the `addResponse` method to set additional API response decorators. (By default, responses for status codes 200, 401, 403, 404, and 500 are generated.) You can also remove default responses by `remove` method.\n\n```ts\nnew SwaggerDecoratorBuilder(target, 'POST')\n  .setBody(body)\n  .removeResponse(200)\n  .removeResponse(403)\n  .removeResponse(404)\n  .addResponse({ status: 201, description: 'create cat' }) ...\n```\n\n5. Call the `build` method to get the final decorator!!\n\n```ts\nnew SwaggerDecoratorBuilder(target, 'GET', returnType)\n  .removeResponse(401)\n  .removeResponse(403)\n  .removeResponse(404)\n  .build();\n```\n\n\u003cbr\u003e\n\n### Conclusion ✨\n\nThe Swagger Decorator Builder facilitates the creation of **concise and readable API documentation**.\n\nThe introduction of the builder pattern streamlines code writing, making API documentation management more efficient. Through this project, users can write cleaner code and effectively manage API documentation.\n\n```ts\n@Patch(':id')\n@UpdateCatDecorator(\n  'Cat',\n  { type: 'uuid', name: 'id', description: 'identifier of cat' },\n  { type: UpdateCatDto, description: 'update dto of cat' },\n)\nupdate(@Param('id') id: string, @Body() updateCatDto: UpdateCatDto) {}\n```\n\n\u003cbr\u003e\n\n### Ongoing Development 🏃\n\nIt's important to note that this project is **still in development**. My goal is to align with and enhance the Swagger decorators based on the official Swagger documentation.\n\n[[KR] 나는 왜 Swagger Decorator Builder를 만들었을까?](https://github.com/kimyu0218/swagger-decorator-builder/wiki/%EB%82%98%EB%8A%94-%EC%99%9C-Swagger-Decorator-Builder%EB%A5%BC-%EB%A7%8C%EB%93%A4%EC%97%88%EC%9D%84%EA%B9%8C%3F)\n\n[[KR] 누구나 사용할 수 있는 패키지를 만들자](https://github.com/kimyu0218/swagger-decorator-builder/wiki/%EB%88%84%EA%B5%AC%EB%82%98-%EC%82%AC%EC%9A%A9%ED%95%A0-%EC%88%98-%EC%9E%88%EB%8A%94-%ED%8C%A8%ED%82%A4%EC%A7%80%EB%A5%BC-%EB%A7%8C%EB%93%A4%EC%9E%90)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkimyu0218%2Fswagger-decorator-builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkimyu0218%2Fswagger-decorator-builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkimyu0218%2Fswagger-decorator-builder/lists"}