{"_id":"@aydin.olmez/express-joi-swagger","name":"@aydin.olmez/express-joi-swagger","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.2":{"name":"@aydin.olmez/express-joi-swagger","version":"1.0.2","description":"Simple non-intrusive library for validating Express routes with Joi and auto-generating Swagger documentation.","main":"./src/index.js","repository":{"type":"git","url":"git+ssh://git@github.com/aydinkodzilla/express-joi-swagger.git"},"license":"MIT","scripts":{"lint":"eslint ./","format":"eslint --fix ./","create-release":"release-it --src.tag","test":"jest --forceExit"},"dependencies":{"express":"^4.17.3","http-status":"^1.5.0","joi":"^17.6.0","joi-to-swagger":"^6.0.1","lodash.clonedeep":"^4.5.0","lodash.merge":"^4.6.2"},"devDependencies":{"eslint":"^4.7.2","eslint-config-google":"^0.9.1","jest":"^23.6.0","release-it":"^7.2.1","supertest":"^3.3.0"},"_id":"@aydin.olmez/express-joi-swagger@1.0.2","gitHead":"5e10137847d5cf0155aa4a249687005fbc6559c2","bugs":{"url":"https://github.com/aydinkodzilla/express-joi-swagger/issues"},"homepage":"https://github.com/aydinkodzilla/express-joi-swagger#readme","_nodeVersion":"20.5.1","_npmVersion":"9.8.0","dist":{"integrity":"sha512-s97nmiAG9pstwiEGXOl4TvNtFYG7BGvUpZCNxeFjpVfj8Ul/n9IeefUuNClFTiRRkztP0NT6+w4DgJrpvzzUyg==","shasum":"d9d6358f1beb62bd10c9031d90fb4823ef98c36e","tarball":"https://registry.npmjs.org/@aydin.olmez/express-joi-swagger/-/express-joi-swagger-1.0.2.tgz","fileCount":9,"unpackedSize":21562,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQC6Bz5O0X8yniQMNyGKE37U7IPVOOklI5HDKCe44ySlAQIgeeHGOSAaBhmiPPFahn1/QseeiUXyJJtMfHl0WnebzAg="}]},"_npmUser":{"name":"aydin.olmez","email":"aydin.olmez@kodzillaistanbul.com"},"directories":{},"maintainers":[{"name":"aydin.olmez","email":"aydin.olmez@kodzillaistanbul.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/express-joi-swagger_1.0.2_1693854766495_0.655316453686309"},"_hasShrinkwrap":false}},"time":{"created":"2023-09-04T19:12:46.345Z","1.0.2":"2023-09-04T19:12:46.686Z","modified":"2023-09-04T19:12:46.991Z"},"maintainers":[{"name":"aydin.olmez","email":"aydin.olmez@kodzillaistanbul.com"}],"description":"Simple non-intrusive library for validating Express routes with Joi and auto-generating Swagger documentation.","homepage":"https://github.com/aydinkodzilla/express-joi-swagger#readme","repository":{"type":"git","url":"git+ssh://git@github.com/aydinkodzilla/express-joi-swagger.git"},"bugs":{"url":"https://github.com/aydinkodzilla/express-joi-swagger/issues"},"license":"MIT","readme":"# IMPORTANT NOTE\nThis package is NOT ready for prime time yet. It is experimental. Please use at your own risk!!\n\n# ExpressJoiSwagger\nThis is a simple, non-intrusive middleware for automatically defining Swagger API definitions for an Express.js webserver. With this package, you'll virtually eliminate the age-old excuse of not having enough time to write an API reference for your services! Some of the features include:\n* Automatic Swagger Reference generation\n* Joi-based request validation\n* Non-intrusive design. Plays nicely with other Express plugins\n* Optional request listener for serving out JSON payload of the auto-generated Swagger reference\n\n## Install\nYarn or NPM:\n```bash\nyarn add express-joi-swagger\n```\n\n```bash\nnpm i express-joi-swagger\n```\n\n## Usage\n### Basic Example\nThe goal is to automatically retrieve your auto-generated API references via `http://<your-server-url>/swagger` (note: this path is configurable). Here's a basic example of how to setup your Express.js server with ExpressJoiSwagger:\n\n```javascript\nconst ExpressJoiSwagger = require('express-joi-swagger');\nconst express = require('express');\nconst Joi = require('joi');\n\nconst app = express();\n\n// Instantiate ExpressJoiSwagger\nconst joiSwagger = new ExpressJoiSwagger({\n  swaggerDefinition: {\n    info: {\n      title: 'Session Service',\n      description: 'RESTful public service for retrieving and setting User Sessions.',\n      version: 'v1.0.2'\n    },\n    host: 'foo.somewhere.com',\n    schemes: ['http', 'https'],\n    consumes: ['application/json'],\n    produces: ['application/json'],\n    defaultResponses: [200, 500]\n  },\n  onValidateError: (errors, req, res, next) => { // global handler for validation errors\n    res.status(400).send(errors);\n  }\n});\n\n// Wrap joiSwagger around the root-level app or router, then\n// define your routes, using Joi for request payload validation:\njoiSwagger.wrapRouter(app).get('/users', {\n  summary: 'GetUsers',\n  description: 'Retrieves a paginated list of users',\n  validate: {\n    query: {\n      limit: Joi.number().default(20).optional().description('Total records returned, for pagination purposes.'),\n      offset: Joi.number().default(0).optional().description('Offset for pagination.')\n    }\n  }\n},\n(req, res) => {\n  res.json([\n    'Greg',\n    'Edward',\n    'Nick',\n    'Richard'\n  ]);\n});\n\n// Wrap joiSwagger around the root-level app before executing the listener\njoiSwagger.wrapRouter(app).listen(8000, () => console.log('Express server listening on port 8000'));\n```\n\n### Defining Arbitrary Swagger Definitions\n```javascript\njoiSwagger.assignDefinition({\n  User: {\n    type: 'object',\n    properties: {\n      id: { type: 'number' },\n      firstName: { type: 'string' }\n    }\n  }\n});\n```\n\n### Defining Route-level Responses\n```\njoiSwagger.wrapRouter(app).get('/users/:userId', {\n  summary: 'GetUserById',\n  description: 'Retrieve a user by ID',\n  responses: {\n    200: {\n      description: 'User Record',\n      schema: {\n        $ref: '#/definitions/User'\n      }\n    }\n  }\n},\n(req, res) => {\n  // ...\n```\n\n### Examples Folder\nMore in-depth examples in the Examples folder\n\n## Caveats\n### Caveat: Express nested routers  *ARE NOT CLEANLY SUPPORTED*\nYou can still use Express nested routers (i.e. `express.Router()`), but you will need to redundantly specify the namespace in the `wrapRouter()` method. Here's an example:\n\n*server.js:* Here, we're using the `/api` namespace to load a nested router:\n```javascript\nconst express = require('express');\nconst joiSwagger = require('./joiSwagger');\nconst app = express();\n\napp.use('/api', require('./routes/foo'));\n\njoiSwagger.wrapRouter(app).listen(8000, () => console.log('listening on port 8000'));\n```\n\n*routes/foo.js:* Notice how we need to re-specify `/api` one more time inside of `wrapRouter()`:\n```javascript\nconst Joi = require('joi');\nconst joiSwagger = require('../joiSwagger');\n\n// '/api' namespace added here as a second argument\nconst router = joiSwagger.wrapRouter(require('express').Router(), '/api');\n\nrouter.get('/foo', {\n  summary: 'GetFoo',\n  description: 'Gets a list of foos',\n  validate: {\n    query: {\n      limit: Joi\n        .number()\n        .min(20)\n        .optional()\n        .description('Total number of results, for pagination purposes.')\n    }\n  }\n},\n(req, res) => {\n  res.send('BLAH');\n});\n\nmodule.exports = router.expressRouter;\n```\n\n\n## TODO\n* Unit tests [HIGH PRIORITY]\n* Serve out a Swagger UI automatically (currently only serves out the Swagger Reference JSON, for use in a separate UI)\n","readmeFilename":"README.md"}