{"id":15766927,"url":"https://github.com/carlansley/swagger2","last_synced_at":"2025-04-15T18:17:25.908Z","repository":{"id":5605798,"uuid":"53541508","full_name":"carlansley/swagger2","owner":"carlansley","description":"Loading, parsing and validating requests to HTTP services based on Swagger v2.0 documents","archived":false,"fork":false,"pushed_at":"2023-01-09T04:28:48.000Z","size":1028,"stargazers_count":25,"open_issues_count":11,"forks_count":16,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-15T18:17:19.902Z","etag":null,"topics":["openapi","swagger","validation"],"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","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null}},"created_at":"2016-03-10T00:12:57.000Z","updated_at":"2024-05-27T04:59:25.000Z","dependencies_parsed_at":"2023-01-11T16:50:50.719Z","dependency_job_id":null,"html_url":"https://github.com/carlansley/swagger2","commit_stats":null,"previous_names":[],"tags_count":44,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlansley%2Fswagger2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlansley%2Fswagger2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlansley%2Fswagger2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlansley%2Fswagger2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/carlansley","download_url":"https://codeload.github.com/carlansley/swagger2/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249126000,"owners_count":21216705,"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":["openapi","swagger","validation"],"created_at":"2024-10-04T13:03:43.118Z","updated_at":"2025-04-15T18:17:25.892Z","avatar_url":"https://github.com/carlansley.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# swagger2\n\nLoading, parsing and validating requests to HTTP services based on Swagger v2.0 documents.\n\n## Benefits\n\n- Fast. Pre-compiled regular expressions and code generation used to validate the inputs and outputs\n  of Swagger 2.0 operations at run-time.\n- Typed. swagger2 is implemented in TypeScript, including a fully annotated TypeScript definition of\n  the Swagger 2.0 document object. Makes working with Swagger objects more pleasant in the IDE of your\n  choosing (WebStorm, Atom, etc).\n\n## Installation\n\n```shell\n$ npm add swagger2\n```\n\n## Usage\n\nBasic loading and validation of swagger 2.0 document:\n\n```\nimport * as swagger from 'swagger2';\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```\n\nYou can compile the document for fast validation of operation requests and responses within\nthe framework of your choosing. Koa 2 example:\n\n```\nlet app = new Koa();\n\n...\napp.use(body());\napp.use(createKoaMiddleware(document));\n...\n\n\nfunction createKoaMiddleware(document: swagger.Document) {\n\n  // construct a validation object, pre-compiling all schema and regex required\n  let compiled = swagger.compileDocument(document);\n\n  return async(context, next) =\u003e {\n\n    if (!context.path.startsWith(document.basePath)) {\n      // not a path that we care about\n      await next();\n      return;\n    }\n\n    let compiledPath = compiled(context.path);\n    if (compiledPath === undefined) {\n      // if there is no single matching path, return 404 (not found)\n      context.status = 404;\n      return;\n    }\n\n    // check the request matches the swagger schema\n    let validationErrors = swagger.validateRequest(compiledPath,\n      context.method, context.request.query, context.request.body);\n    if (validationErrors === undefined) {\n      // operation not defined, return 405 (method not allowed)\n      context.status = 405;\n      return;\n    }\n\n    if (validationErrors.length \u003e 0) {\n      context.status = 400;\n      context.body = {\n        code: 'SWAGGER_REQUEST_VALIDATION_FAILED',\n        errors: validationErrors\n      };\n      return;\n    }\n\n    // wait for the operation to execute\n    await next();\n\n    // check the response matches the swagger schema\n    let error = swagger.validateResponse(compiledPath, context.method, context.status, context.body);\n    if (error) {\n      error.where = 'response';\n      context.status = 500;\n      context.body = {\n        code: 'SWAGGER_RESPONSE_VALIDATION_FAILED',\n        errors: [error]\n      };\n    }\n  };\n}\n\n\n```\n\nThere is a complete implementation of this example/use-case in the \u003ca href=\"https://github.com/carlansley/swagger2-koa\"\u003eswagger2-koa\u003c/a\u003e module,\nso if you're using Koa 2 it may make sense to use that instead of swagger2 directly.\n\n## Limitations\n\n- currently only supports synchronous loading of full documents (via swagger.loadDocumentSync)\n- does not support validation of file attachments\n- does not support validation of mime-types\n- requires node v16.0 or above\n\n## Development\n\nFirst, grab the source from \u003ca href=\"https://github.com/carlansley/swagger2\"\u003eGitHub\u003c/a\u003e.\n\nFrom within the swagger2 directory, to run tests:\n\n```shell\n$ npm install\n$ npm test\n```\n\nTo see code coverage in a web-browser:\n\n```shell\n$ npm run ci:coverage\n$ open coverage/lcov-report/index.html (on Mac)\n```\n\nTo clean up:\n\n```shell\n$ npm run clean\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarlansley%2Fswagger2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcarlansley%2Fswagger2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarlansley%2Fswagger2/lists"}