{"id":20516150,"url":"https://github.com/aftership/swagger-ajv","last_synced_at":"2025-07-25T23:32:41.537Z","repository":{"id":32499937,"uuid":"130676579","full_name":"AfterShip/swagger-ajv","owner":"AfterShip","description":"Old name: koa-swagger-ajv","archived":false,"fork":false,"pushed_at":"2023-03-04T03:29:03.000Z","size":1143,"stargazers_count":16,"open_issues_count":6,"forks_count":18,"subscribers_count":26,"default_branch":"master","last_synced_at":"2025-06-21T07:39:52.015Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/AfterShip.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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":"2018-04-23T09:58:34.000Z","updated_at":"2022-03-29T06:03:58.000Z","dependencies_parsed_at":"2024-06-21T17:40:37.454Z","dependency_job_id":null,"html_url":"https://github.com/AfterShip/swagger-ajv","commit_stats":null,"previous_names":[],"tags_count":39,"template":false,"template_full_name":null,"purl":"pkg:github/AfterShip/swagger-ajv","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AfterShip%2Fswagger-ajv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AfterShip%2Fswagger-ajv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AfterShip%2Fswagger-ajv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AfterShip%2Fswagger-ajv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AfterShip","download_url":"https://codeload.github.com/AfterShip/swagger-ajv/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AfterShip%2Fswagger-ajv/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267083574,"owners_count":24033324,"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","status":"online","status_checked_at":"2025-07-25T02:00:09.625Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2024-11-15T21:27:01.419Z","updated_at":"2025-07-25T23:32:41.467Z","avatar_url":"https://github.com/AfterShip.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# swagger-ajv \u0026middot; \n\nThe middleware for validating and documenting express and koa applications.\n- Validation is done using AJV.\n- Documentation is done using Swagger.\n\nCompatible with node \u003e= 4\n\n## Specification\n\nNOTE: The middleware must be applied to the router not the application when using koa.\n\nThe documentation should be written using OpenAPI 3.0 specification with the differences listed below. The differences with JSON schema can be noted [here](https://swagger.io/docs/specification/data-models/keywords). When writing schema for your application please note that the keywords must be used in a way that can be supported by both Swagger and AJV.\n\n- `type` can be an array with `\"null\"` as the second element when `\"nullable\": true` property needs to be used as mentioned in the OpenAPI.\n\n```\n\"type\": \"string\"\n```\n\n```\n\"type\": [\"string\", \"null\"],\n\"nullable\": true\n```\n\n## Reference\n\n`swaggerAjv` is used to refer to the library which would be required as `require('swagger-ajv')`\n\n### Middlewares\n\nswaggerAjv.middlewares.express\n\n- docs\n- validation\n\nswaggerAjv.middlewares.koa\n\n- docs\n- validation\n\n\u003e docs\n\npass the schema object as specified by openapi\n\n\u003e validation\n\npass an object should contain `components`, `paths` and `ajvOptions`\n`paths` and `components` are the schemas that can be referenced from `ajv` to use\n`ajvOptions` are all the options that can be passed to initialise an `ajv` instance\n\n\n### Utils\n\n\u003e swaggerAjv.mergeSchemas\nthe first parameter is a string specifying the path of the folder containing schemas\nthe second parameter specifies the options on how the schemas are read\n\n1. `useDirStructre`\n\n\n\n## Test\n\n```\nyarn test\n```\n\n## Building\n\n```\nyarn build\n```\n\n## Examples\n\n### Define schemas for your application\n\n\u003e Componenet.json\n\nschema for new component should be defined under `components.schemas` if written in separate files\n```json\n{\n  \"components\": {\n    \"schemas\": {\n      \"Component\": {\n        \"type\": \"object\"\n      }\n    }\n  }\n}\n```\n\n\u003e swagger.json\n\nkeys other than `components` and `paths` defined in a separate file\n```json\n{\n  \"openapi\": \"3.0.0\"\n}\n```\n\n\u003e path.json\n\nschema for a path should be defined as under `paths` key if written in separate files\n```json\n{\n  \"paths\": {\n    \"/post\": {\n      \"post\": {\n        \"requestBody\": {\n          \"content\": {\n            \"application/json\": {\n              \"schema\": {\n                \"type\": \"object\",\n                \"properties\": {\n                  \"body\": {\n                    \"type\": [\"string\", \"null\"]\n                  }\n                }\n              }\n            }\n          }\n        },\n        \"responses\": {\n          \"200\": {\n            \"content\": {\n              \"application/json\": {\n                \"schema\": {\n                  \"properties\": {\n                    \"data\": {\n                      \"$ref\": \"#/components/schemas/Component\"\n                    }\n                  }\n                }\n              }\n            }\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n### Write middleware in your favourite framework\n\n- Express `examples/express.js`\n\n```\n'use strict';\n\nconst path = require('path');\n\nconst swaggerAjv = require('../src');\n\nconst {docs, validation} = swaggerAjv.middlewares.express;\n\nconst {mergeSchemas} = swaggerAjv.utils;\n\n// load schema definitions\nconst schemas = mergeSchemas(\n\tpath.resolve(__dirname, 'schemas')\n);\n\n// define ajvOptions\nconst ajvOptions = {};\n// custom keywarods\nconst ajvKeywords = [{\n\t\t\tname: 'mustPositive',\n\t\t\tdef: {\n\t\t\t\tvalidate: (schema, data) =\u003e {\n\t\t\t\t\treturn schema ? data \u003e 0 : true;\n\t\t\t\t}\n\t\t\t}\n\t\t}]\n// We have embedded [ajv-errors](https://github.com/epoberezkin/ajv-errors)\nconst ajvErrorsOptions = {};\n\n// export middlewares for your application\nexports.docs = docs(schemas.swagger);\nexports.validation = validation(Object.assign(\n\tschemas.ajv,\n\t{ ajvOptions,\n    ajvKeywords,\n    ajvErrorsOptions }\n));\n```\n\n- Koa `examples/koa.js`\n\n```\n'use strict';\n\nconst path = require('path');\n\nconst swaggerAjv = require('../src');\n\nconst {docs, validation} = swaggerAjv.middlewares.koa;\n\nconst {mergeSchemas} = swaggerAjv.utils;\n\n// load schema definitions\nconst schemas = mergeSchemas(\n\tpath.resolve(__dirname, 'schemas')\n);\n\n// define ajvOptions\nconst ajvOptions = {};\n// custom keywarods\nconst ajvKeywords = [{\n\t\t\tname: 'mustPositive',\n\t\t\tdef: {\n\t\t\t\tvalidate: (schema, data) =\u003e {\n\t\t\t\t\treturn schema ? data \u003e 0 : true;\n\t\t\t\t}\n\t\t\t}\n\t\t}]\n// We have embedded [ajv-errors](https://github.com/epoberezkin/ajv-errors)\nconst ajvErrorsOptions = {};\n\n// export middlewares for your application\nexports.docs = docs(schemas.swagger);\nexports.validation = validation(Object.assign(\n\tschemas.ajv,\n\t{ ajvOptions,\n    ajvKeywords,\n    ajvErrorsOptions  }\n));\n```\n\n## Credits\n\n- [AJV](https://github.com/epoberezkin/ajv)\n- [Swagger](https://github.com/swagger-api/swagger-ui)\n\n## License\n\n[MIT](https://github.com/AfterShip/swagger-ajv/blob/master/LICENSE.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faftership%2Fswagger-ajv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faftership%2Fswagger-ajv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faftership%2Fswagger-ajv/lists"}