{"id":14986693,"url":"https://github.com/smartrecruiters/openapi-first","last_synced_at":"2025-06-16T03:03:04.422Z","repository":{"id":30495561,"uuid":"124390318","full_name":"smartrecruiters/openapi-first","owner":"smartrecruiters","description":"Start your node REST app with designing API first!","archived":false,"fork":false,"pushed_at":"2024-08-07T14:36:43.000Z","size":151,"stargazers_count":40,"open_issues_count":6,"forks_count":5,"subscribers_count":33,"default_branch":"master","last_synced_at":"2025-05-21T20:47:34.575Z","etag":null,"topics":["connect","oas3","openapi","openapi-specification","openapi3"],"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/smartrecruiters.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"docs/CODE_OF_CONDUCT.md","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-03-08T12:46:22.000Z","updated_at":"2025-01-12T12:09:40.000Z","dependencies_parsed_at":"2024-08-07T16:59:11.073Z","dependency_job_id":null,"html_url":"https://github.com/smartrecruiters/openapi-first","commit_stats":{"total_commits":48,"total_committers":10,"mean_commits":4.8,"dds":0.6041666666666667,"last_synced_commit":"50a61b0e0bd0bc3686e19a73b2456af62b16e842"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/smartrecruiters/openapi-first","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartrecruiters%2Fopenapi-first","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartrecruiters%2Fopenapi-first/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartrecruiters%2Fopenapi-first/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartrecruiters%2Fopenapi-first/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smartrecruiters","download_url":"https://codeload.github.com/smartrecruiters/openapi-first/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartrecruiters%2Fopenapi-first/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260089348,"owners_count":22957126,"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":["connect","oas3","openapi","openapi-specification","openapi3"],"created_at":"2024-09-24T14:13:21.947Z","updated_at":"2025-06-16T03:03:04.382Z","avatar_url":"https://github.com/smartrecruiters.png","language":"JavaScript","readme":"# @smartrecruiters/openapi-first\n\n[![NPM Version][npm-image]][npm-url]\n[![NPM Downloads][downloads-image]][downloads-url]\n[![Node.js Version][node-version-image]][node-version-url]\n[![Licence][license-image]][license-url]\n[![Build][travis-image]][travis-url]\n\nStart your node REST app with designing API first!\n\n## Is it for you?\n\nIf you:\n- use OpenAPI Specification 3.0 to document your REST APIs written in node.js,\n- like design first approach regarding REST APIs\n- want your specification to be single source of truth of your API,\n- want to handle validation and parsing of requests query, path, body, content-type in a unified manner for all API endpoints,\n\nthen `@smartrecruiters/openapi-first` is what you are looking for!\n\nThis module initializes your API connect-style application with specification in\n[OpenAPI Specification 3.0](https://openapis.org/specification) format.\n\n## How to start\n\nLet's say you have specification in OpenAPI Specification 3.0 in `spec.json`:\n\n```javascript\n{\n    \"openapi\": \"3.0.0\",\n    \"info\": {\n        \"version\": \"1.0.0\",\n        \"title\": \"Hello World API\"\n    },\n    \"paths\": {\n        \"/hello\": {\n            \"get\": {\n                \"responses\": {\n                    \"200\": {\n                        \"description\": \"Success\",\n                        \"content\": {\n                            \"application/json\": {\n                                \"schema\": {\n                                    \"$ref\": \"#/components/schemas/Greeting\"\n                                }\n                            }\n                        }\n                    }\n                },\n                \"x-swagger-router-controller\": \"greeting/hello\",\n                \"parameters\": [\n                    {\n                        \"in\": \"query\",\n                        \"name\": \"name\",\n                        \"schema\": {\n                            \"type\": \"string\",\n                            \"default\": \"world\"\n                        }\n                    }\n                ]\n            }\n        }\n    },\n    \"components\": {\n        \"schemas\": {\n            \"Greeting\": {\n                \"type\": \"object\",\n                \"properties\": {\n                    \"greeting\": {\n                        \"type\": \"string\"\n                    }\n                }\n            }\n        }\n    }\n}\n```\n\nNow you can implement connect-style middleware with \"business logic\" in `greeting/hello.js`:\n\n```javascript\nmodule.exports = function(req, res) {\n    res.status(200).json({greeting: `Hello, ${req.query.name}!`})\n}\n```\n\nNow, let's make an `app.js` file:\n```javascript\nconst openApiFirst = require('@smartrecruiters/openapi-first')\nconst express = require('express')\n\n// create express app\nconst app = express()\n\nconst spec = require('./spec.json')\n\n// create open api specification initializer\nconst api = openApiFirst(app, spec)\n\n// to enable setting default values on empty query params\napi.use(require('@smartrecruiters/openapi-first/middlewares/query/defaults')())\n\n// to link the specification with code in 'api' directory\napi.use(require('@smartrecruiters/openapi-first/middlewares/controllers/by-property')({dir: __dirname}))\n\napp.listen(8080)\n\n```\n\nWe can now run the application:\n```bash\nnode app\n```\nTo verify it's working, let's hit the endpoint:\n```bash\ncurl localhost:8080/hello?who=world\n```\nThe response should be 200 with body:\n```json\n{\"greeting\":\"Hello, world!\"}\n```\n\n## openapi middlewares\n\nYou can use one of the middlewares under `@smartrecruiters/middlewares/*` or create your own. Such middlewares will be\napplied to connect-style app for each operation as they are specification and operation aware. For instance,\n`@smartrecruiters/middlewares/query/validate` middleware will be applied to any and only operation which has query\nparameters defined, passing an Error to `next` callback when `req.query` is invalid.\n\nCurrently following middlewares are available:\n- request body validation,\n- request body parsing (e.g. form string parameters to types specified in API documentation)\n- setting default values on request body,\n- query parameters validation,\n- setting default query parameters values\n- removing unspecified query parameters,\n- path parameters validation,\n- content type validation,\n- routing to appropriate controller,\n- oauth scopes authorization,\n- error handlers (`MissingRequiredScopes`).\n\n### Validation middlewares\n\nMiddlewares for request body, query and path validation expects schema validators in order to be created.\nThe recommended schema validator is [`@smartrecruiters/openapi-schema-validator`](https://www.npmjs.com/package/@smartrecruiters/openapi-schemas-validator)\n\n### Create your own openapi middleware\n\nAdding your own openapi is very simple. Let's say your operation has extension\n[OpenAPI Specification 3.0 Specification Extension](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#specificationExtensions) 'x-only-admin'.\nIf it is set on, this will mean that only users with admin can use this method.\nAssuming some preceding middleware is setting `req.user.role`, you can write a simple openapi middleware\nthat will gather information from operation object and act accordingly:\n```javascript\nconst onlyAdminMiddleware = operation =\u003e\n    (req, res, next) =\u003e {\n        if(operation['x-only-admin'] \u0026\u0026 req.user.role !== \"admin\") {\n            res.status(403).json(\"Access forbidden. For this operation, you need to have admin role\")\n        }\n        return next()\n    }\n```\n\n## Contributing\n\nPlease see our [Code of conduct](docs/CODE_OF_CONDUCT.md) and [Contributing guidelines](docs/CONTRIBUTING.md)\n\n## License\n\n[MIT](LICENSE)\n\n[npm-image]: https://img.shields.io/npm/v/@smartrecruiters/openapi-first.svg\n[npm-url]: https://www.npmjs.com/package/@smartrecruiters/openapi-first\n[downloads-image]: https://img.shields.io/npm/dm/@smartrecruiters/openapi-first.svg\n[downloads-url]: https://www.npmjs.com/package/@smartrecruiters/openapi-first\n[node-version-image]: https://img.shields.io/node/v/@smartrecruiters/openapi-first.svg\n[node-version-url]: https://nodejs.org/en/download/\n[license-url]: https://github.com/smartrecruiters/openapi-first/blob/master/LICENSE\n[license-image]: https://img.shields.io/npm/l/@smartrecruiters/openapi-first.svg\n[travis-url]: https://travis-ci.com/smartrecruiters/openapi-first\n[travis-image]: https://api.travis-ci.com/smartrecruiters/openapi-first.svg?branch=master\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmartrecruiters%2Fopenapi-first","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmartrecruiters%2Fopenapi-first","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmartrecruiters%2Fopenapi-first/lists"}