{"id":13800263,"url":"https://github.com/carlansley/swagger2-koa","last_synced_at":"2025-04-06T18:17:13.505Z","repository":{"id":5990834,"uuid":"54420213","full_name":"carlansley/swagger2-koa","owner":"carlansley","description":"Koa 2 middleware for swagger2","archived":false,"fork":false,"pushed_at":"2024-01-30T08:10:00.000Z","size":962,"stargazers_count":98,"open_issues_count":10,"forks_count":28,"subscribers_count":9,"default_branch":"main","last_synced_at":"2024-04-14T12:38:45.828Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/carlansley.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-03-21T20:25:57.000Z","updated_at":"2024-04-30T12:13:27.987Z","dependencies_parsed_at":"2024-05-20T08:30:44.254Z","dependency_job_id":null,"html_url":"https://github.com/carlansley/swagger2-koa","commit_stats":{"total_commits":132,"total_committers":7,"mean_commits":"18.857142857142858","dds":"0.10606060606060608","last_synced_commit":"258f9a07caea6a8bd00edd25f41f04685325a706"},"previous_names":[],"tags_count":52,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlansley%2Fswagger2-koa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlansley%2Fswagger2-koa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlansley%2Fswagger2-koa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlansley%2Fswagger2-koa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/carlansley","download_url":"https://codeload.github.com/carlansley/swagger2-koa/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247526768,"owners_count":20953143,"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":[],"created_at":"2024-08-04T00:01:10.906Z","updated_at":"2025-04-06T18:17:13.481Z","avatar_url":"https://github.com/carlansley.png","language":"TypeScript","funding_links":[],"categories":["仓库"],"sub_categories":["中间件"],"readme":"# swagger2-koa\n\nKoa 2 async-style middleware for loading, parsing and validating requests via swagger2.\n\n- `router(document) =\u003e koa2-style Router`\n- `validate(document) =\u003e koa2 middleware`\n\n## Installation\n\n```shell\n$ npm add swagger2-koa\n```\n\n## Usage\n\n### `router(document) =\u003e koa2-style Router`\n\nThis is the easiest way to use swagger2-koa; it creates a standalone koa server, adds the `validate` middleware, and returns a\nRouter object that allows you to add your route implementations.\n\n```\nimport * as swagger from 'swagger2';\nimport {router as swaggerRouter, Router} from 'swagger2-koa';\n\n...\nconst document = swagger.loadDocumentSync('./swagger.yml');\nconst router: Router = swaggerRouter(document);\n\nrouter.get('/ping', async (context) =\u003e {\n  context.status = 200;\n  context.body = {\n    serverTime: new Date().toISOString()\n  };\n});\n\n...\n\nrouter.app()         // get the koa 2 server\n  .listen(3000);     // start handling requests on port 3000\n\n```\n\nNote: in addition to `validate` (described below), `router` adds the following middleware to its koa server:\n\n- `@koa/cors`\n- `@koa/router`\n- `koa-bodyparser`\n\n### `validate(document) =\u003e koa2 middleware`\n\nIf you already have a Koa server, this middleware adds basic loading and validation of HTTP requests and responses against\nswagger 2.0 document:\n\n```javascript\nimport * as swagger from 'swagger2';\nimport { validate } from 'swagger2-koa';\n\nconst app = new Koa();\n\n// load YAML swagger file\nconst document = swagger.loadDocumentSync('./swagger.yml');\n\n// validate document\nif (!swagger.validateDocument(document)) {\n  throw Error(`./swagger.yml does not conform to the Swagger 2.0 schema`);\n}\n\napp.use(body());\napp.use(validate(document));\n```\n\nThe `validate` middleware behaves as follows:\n\n- expects context.body to contain request body in object form (e.g. via use of koa-body)\n- if the request is for a path not defined in swagger document, an HTTP 404 is returned to the client (subsequent middleware is never processed).\n- if the request body does not validate, an HTTP 400 is returned to the client (subsequent middleware is never processed)\n- if the response body does not validate, an HTTP 500 is returned to the client\n\nFor either request (HTTP 400) or response (HTTP 500) errors, details of the schema validation error are passed back in the body. e.g.:\n\n```JSON\n{\n  \"code\": \"SWAGGER_RESPONSE_VALIDATION_FAILED\",\n  \"errors\": [{\n     \"actual\": {\"badTime\": \"mock\"},\n     \"expected\": {\n        \"schema\": {\"type\": \"object\", \"required\": [\"time\"], \"properties\": {\"time\": {\"type\": \"string\", \"format\": \"date-time\"}}}\n     },\n     \"where\": \"response\"\n  }]\n}\n```\n\n## Debugging\n\nThis library uses [`debug`](https://github.com/visionmedia/debug), which can be activated using the\n`DEBUG` environment variable:\n\n```shell\nexport DEBUG=swagger2-koa:*\n```\n\n## Limitations\n\n- only supports Koa 2-style async/await middleware interface\n- requires node version 16 and above\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarlansley%2Fswagger2-koa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcarlansley%2Fswagger2-koa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarlansley%2Fswagger2-koa/lists"}