{"id":26204653,"url":"https://github.com/jonace-mpelule/openapi-express-decorators","last_synced_at":"2026-04-07T23:32:02.550Z","repository":{"id":281910561,"uuid":"946838312","full_name":"jonace-mpelule/openapi-express-decorators","owner":"jonace-mpelule","description":"🎉 A lightweight, type-safe library for generating OpenAPI documentation using decorators in Express.js applications. This package allows you to define OpenAPI metadata (paths, parameters, responses, etc.) directly in your controllers using decorators, making it easy to keep your API documentation in sync with your code","archived":false,"fork":false,"pushed_at":"2025-03-11T19:37:36.000Z","size":39,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-19T20:37:54.623Z","etag":null,"topics":["api-documentation","decorators","documentation","expressjs","nodejs","openapi","swagger","swagger-ui","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/jonace-mpelule.png","metadata":{"files":{"readme":"README.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":"2025-03-11T18:51:43.000Z","updated_at":"2025-03-18T08:51:54.000Z","dependencies_parsed_at":"2025-03-12T14:00:29.029Z","dependency_job_id":null,"html_url":"https://github.com/jonace-mpelule/openapi-express-decorators","commit_stats":null,"previous_names":["jonace-mpelule/openapi-express-decorators"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jonace-mpelule/openapi-express-decorators","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonace-mpelule%2Fopenapi-express-decorators","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonace-mpelule%2Fopenapi-express-decorators/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonace-mpelule%2Fopenapi-express-decorators/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonace-mpelule%2Fopenapi-express-decorators/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jonace-mpelule","download_url":"https://codeload.github.com/jonace-mpelule/openapi-express-decorators/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonace-mpelule%2Fopenapi-express-decorators/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31533823,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"ssl_error","status_checked_at":"2026-04-07T16:28:06.951Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["api-documentation","decorators","documentation","expressjs","nodejs","openapi","swagger","swagger-ui","typescript"],"created_at":"2025-03-12T04:25:06.697Z","updated_at":"2026-04-07T23:32:02.533Z","avatar_url":"https://github.com/jonace-mpelule.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🎉 OpenAPI Express Decorators\n\nA lightweight, type-safe library for generating OpenAPI documentation using decorators in Express.js applications. This package allows you to define OpenAPI metadata (paths, parameters, responses, etc.) directly in your controllers using decorators, making it easy to keep your API documentation in sync with your code.\n\n## Features\n\n- **🎉 Decorator-based OpenAPI documentation**: Define OpenAPI metadata using decorators like `@OpenApiGet`, `@OpenApiPost`, etc.\n- **🔑 Type-safe schemas**: Use TypeScript types to define request/response schemas and parameters.\n- **🎨 Customizable**: Supports custom schemas, parameters, and responses.\n- **⚡️ Easy integration**: Works seamlessly with Express.js and other HTTP handler libraries.\n\n---\n\n## Installation\n\nInstall the package using npm:\n\n```bash\nnpm install openapi-express-decorators\n```\n\nOr using yarn:\n\n```bash\nyarn add openapi-express-decorators\n```\n\n---\n\n## Setup\n#### 1. Enable reflect-metadata\nEnsure reflect-metadata is enabled in your project. Add the following line at the top of your entry file (e.g., `index.ts` or `server.ts`):\n\n```typescript\nimport 'reflect-metadata';\n```\n#### 2. Configure tsconfig.json\nMake sure your `tsconfig.json` has the following options enabled:\n\n```json\n{\n  \"compilerOptions\": {\n    \"experimentalDecorators\": true,\n    \"emitDecoratorMetadata\": true\n  }\n}\n```\n\n#### 3. Set Up Express.js \u0026 @Reflet/Express\nInstall Express.js if you haven't already, and optionally you can use `@reflet/express` for better MVC for express.js\n\n```bash\nnpm install express @reflet/express\n```\n---\n## Usage\n#### 1. Define Schemas\nUse the createSchema utility to define request/response schemas.\n\n```typescript\nimport { createSchema, SchemaDefinition } from 'openapi-express-decorators';\n\nconst RegisterUserDTO: SchemaDefinition = {\n    name: {\n        type: 'string',\n        required: true,\n        example: 'John Doe',\n    },\n    email: {\n        type: 'string',\n        required: true,\n        example: 'jonace@example.com',\n    },\n    password: {\n        type: 'string',\n        required: true,\n        example: '*****',\n    },\n};\n\nexport const RegisterUserSchema = createSchema('RegisterUserDTO', RegisterUserDTO);\n```\n\n#### 2. Define Parameters\nUse the Parameter type to define path, query, or header parameters.\n\n```typescript\nimport { Parameter } from 'openapi-express-decorators';\n\nexport const userIdParam: Parameter = {\n    name: 'userId',\n    in: 'query',\n    description: 'The ID of the user',\n    required: true,\n    schema: {\n        type: 'string',\n        example: '12345',\n    },\n};\n```\n\n#### 3. Create Controllers\nUse the `@OpenApiRoute` decorator to define routes and OpenAPI \n\n```typescript\nimport { Router, Res, Post } from '@reflet/express';\nimport { OpenApiRoute } from 'openapi-express-decorators';\nimport { RegisterUserSchema } from './schemas';\nimport { userIdParam } from \"./parameters\"\n\n@Router('/v1/auth')\nexport class AuthController {\n    @OpenApiRoute('POST', '/v1/auth/register', {\n        summary: 'Register User',\n        tags: ['Auth'],\n        description: 'Register a new user with email and password,\n         requestBody: {\n            content: {\n                'application/json': {\n                    schema: {\n                        $ref: \"#/components/schemas/RegisterUserSchema\"\n                    },\n                },\n            },\n        },\n        responses: {\n            200: {\n                description: 'Success',\n                content: {\n                    'application/json': {\n                        example: {\n                            code: \"success\", \n                            message: \"User registered\"\n                        }\n                    },\n                },\n            },\n        },\n    })\n      \n    async register(req: CustomRequest, res: Res) {\n        const userId = req.query.userId;\n        // HTTP handler logic\n    }\n\n    @OpenApiRoute('DELETE', '/v1/auth/delete-account/{userId}', {\n        summary: 'Delete User',\n        parameters: [\n            {\n                name: 'userId',\n                in: 'path',\n                description: 'The ID of the account to be deleted',\n                required: true,\n                schema: {\n                    type: 'string',\n                    example: '1234',\n                },\n            },\n            // or use the imported `userIdParam`\n        ],\n       \n        responses: {\n            200: {\n                description: 'Success',\n                content: {\n                    'application/json': {\n                        example: {\n                            code: \"success\", \n                            message: \"User deleted successfuly\"\n                        }\n                    },\n                },\n            },\n        },\n    })\n    @Delete('/delete-account/:userId')\n    async deleteAccount(req: CustomRequest, res: Res) {\n        const userId = req.params.userId;\n        // HTTP handler logic\n    }\n}\n```\n#### 4. Generate OpenAPI Documentation\nUse the `generateOpenApiDocs` function to generate the OpenAPI specification.\n\n```typescript\nimport { generateOpenApiDocs } from 'openapi-express-decorators';\nimport { AuthController } from './controllers/auth.controller';\nimport { RegisterUserSchema } from './schemas';\n\n// controllers that you have your open api routes\nconst routeControllers = [AuthController, ...otherControllers ];\n\nexport const swaggerSpec = generateOpenApiDocs(routeControllers, {\n    openapi: '3.0.0',\n    info: {\n        title: 'My API Documentation',\n        version: '1.0.0',\n    },\n    servers: [\n        {\n            url: \"https://dev.myapi.com\",\n            description: \"Development Server\"\n        },\n    ],\n    tags: [\n        {\n            name: \"Auth\",\n            description: \"Auth related authentication endpoints\"\n        },\n    ],\n    paths: {},\n    components: {\n        schemas: {\n            RegisterUserSchema,\n        },\n    },\n});\n\n```\n#### 5. Serve Swagger UI\nServe the OpenAPI documentation using Swagger UI.\n\n```typescript\nimport express from 'express';\nimport swaggerUi from 'swagger-ui-express';\nimport { swaggerSpec } from \"./swaggerspec.config\"\n\nconst app = express();\n\napp.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));\napp.use('/openapi', ) // -\u003e export your openapi document\n\napp.listen(3000, () =\u003e {\n    console.log('Server is running on http://localhost:3000');\n});\n```\n### Type Definitions\nThe package exports the following types for type-safe usage:\n\n#### SchemaDefinition\nDefines the structure of a schema.\n\n```typescript\ninterface SchemaDefinition {\n    [key: string]: {\n        type: 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'null';\n        required?: boolean;\n        example?: any;\n        description?: string;\n    };\n}\n```\n#### Parameter\nDefines a parameter `(path, query, or header)`.\n\n```typescript\ninterface Parameter {\n    name: string;\n    in: 'path' | 'query' | 'header';\n    description?: string;\n    required?: boolean;\n    schema: {\n        type: 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'null';\n        example?: any;\n        description?: string;\n    };\n}\n```\n#### OpenApiRouteOptions\nDefines options for the `@OpenApiRoute` decorator.\n\n```typescript\ninterface OpenApiRouteOptions {\n    summary?: string;\n    description?: string;\n    parameters?: Parameter[];\n    requestBody?: {\n        content: {\n            'application/json': {\n                schema: SchemaDefinition;\n            };\n        };\n    };\n    responses: {\n        [statusCode: string]: {\n            description: string;\n            content?: {\n                'application/json': {\n                    schema: SchemaDefinition;\n                };\n            };\n        };\n    };\n}\n```\n---\n\n\n## License\nThis project is licensed under the MIT License. See the LICENSE file for details.\n\n## Acknowledgments\nInspired by Swagger and OpenAPI.\n\nBuilt with ❤️ by [Jonace Mpelule](https://github.com/jonace-mpelule).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonace-mpelule%2Fopenapi-express-decorators","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjonace-mpelule%2Fopenapi-express-decorators","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonace-mpelule%2Fopenapi-express-decorators/lists"}