{"id":26468796,"url":"https://github.com/donatocardoso/express-swagger-delta","last_synced_at":"2025-03-19T16:57:50.882Z","repository":{"id":56394613,"uuid":"234751590","full_name":"donatocardoso/express-swagger-delta","owner":"donatocardoso","description":"Library for configuration, creation and documentation for API servers with 'Express' and 'Swagger'","archived":false,"fork":false,"pushed_at":"2021-04-16T18:07:08.000Z","size":136,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-11T21:25:02.650Z","etag":null,"topics":["api","express","express-swagger-delta","node","openapi","swagger","swagger-documentation"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/express-swagger-delta","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/donatocardoso.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":null,"support":null}},"created_at":"2020-01-18T15:03:04.000Z","updated_at":"2022-05-24T14:30:38.000Z","dependencies_parsed_at":"2022-08-15T18:00:15.647Z","dependency_job_id":null,"html_url":"https://github.com/donatocardoso/express-swagger-delta","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donatocardoso%2Fexpress-swagger-delta","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donatocardoso%2Fexpress-swagger-delta/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donatocardoso%2Fexpress-swagger-delta/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donatocardoso%2Fexpress-swagger-delta/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/donatocardoso","download_url":"https://codeload.github.com/donatocardoso/express-swagger-delta/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244470242,"owners_count":20457906,"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":["api","express","express-swagger-delta","node","openapi","swagger","swagger-documentation"],"created_at":"2025-03-19T16:57:50.244Z","updated_at":"2025-03-19T16:57:50.877Z","avatar_url":"https://github.com/donatocardoso.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003clink href=\"main.css\" rel=\"stylesheet\"\u003e\u003c/link\u003e\n\n# ✅ express-swagger-delta\n\nFast, unopinionated, minimalist web framework for [node](http://nodejs.org).\n\n[![NPM Version][npm-image]][npm-url]\n[![NPM Downloads][downloads-image]][downloads-url]\n![badge-statements]\n![badge-branches]\n![badge-functions]\n![badge-lines]\n\n## 🔹 Installation\n\nThis is a [Node.js](https://nodejs.org/en/) module available through the\n[npm registry](https://www.npmjs.com/).\n\nBefore installing, [download and install Node.js](https://nodejs.org/en/download/).\n\nInstallation is done using the\n[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):\n\n```bash\n$ npm install express-swagger-delta\n```\n\nOU\n\n```bash\n$ yarn add express-swagger-delta\n```\n\n## 🔹 Usage\n\nTo start using the library, it is necessary to create a base configuration file, following the structure:\n\n**Note:** Follows the same structure pattern as the [swagger.js documentation](https://swagger.io/docs/specification/basic-structure/) (openapi: 3.0.0).\n\n```js\nimport { description, name, version } from '../../package.json';\n\nexport const layout = {\n  explorer: false,\n  customSiteTitle: 'Example Documentation',\n  customCss: '.swagger-ui .topbar { display: none }',\n  swaggerOptions: {\n    docExpansion: 'none',\n  },\n};\n\nexport const specification = {\n  info: {\n    name: name,\n    version: version,\n    description: description,\n    title: 'Example Documentation',\n  },\n  servers: [\n    {\n      url: `http://localhost:8080/api`,\n    },\n  ],\n  components: {\n    securitySchemes: {\n      ExampleKey: {\n        in: 'header',\n        type: 'apiKey',\n        name: 'ExampleKey',\n      },\n    },\n    schemas: {\n      Return: {\n        type: 'object',\n        properties: {\n          statusCode: {\n            type: 'integer',\n            format: 'int64',\n            description: 'Request Status Code',\n          },\n          message: {\n            type: 'string',\n            description: 'Request Status Message',\n          },\n          content: {\n            type: 'object',\n            description: 'Request Content',\n          },\n        },\n      },\n    },\n    responses: {\n      default: {\n        description: 'Api Default Return',\n        content: {\n          'application/json': {\n            schema: {\n              $ref: '#/components/schemas/Return',\n            },\n          },\n        },\n      },\n    },\n  },\n};\n```\n\nThat done, you need to configure the server, which can be done as follows:\n\n```js\nimport { json, urlencoded } from 'body-parser';\nimport cors from 'cors';\nimport helmet from 'helmet';\nimport ExpressSwagger from '../../dist/index';\nimport ExampleController from '../controllers/ExampleController';\nimport AuthService from '../services/AuthService';\nimport { layout, specification } from './swagger';\n\nclass Server {\n  constructor() {\n    this.server = ExpressSwagger.Server;\n\n    this.server.NODE_ENV = 'test';\n    this.server.BASE_HOST = 'localhost';\n    this.server.BASE_PATH = '/api';\n    this.server.PORT = 8080;\n\n    this.server.setSwaggerProps({\n      layout: layout,\n      specification: specification,\n    });\n\n    this.server.app.use(cors());\n    this.server.app.use(helmet());\n    this.server.app.use(urlencoded({ extended: true }));\n    this.server.app.use(json({ limit: '2gb' }));\n\n    this.server.middleware = this.middleware;\n    this.server.authMiddleware = this.authMiddleware;\n\n    ExampleController.setRoutes();\n\n    this.server.initialize();\n  }\n\n  authMiddleware(req, res, next) {\n    AuthService.checkAuth(req)\n      .then((auth) =\u003e {\n        switch (auth.statusCode) {\n          case 200:\n            return next();\n          case 400:\n            return res.status(400).json(auth);\n          case 401:\n            return res.status(401).json(auth);\n        }\n      })\n      .catch((err) =\u003e res.status(500).json(err));\n  }\n\n  middleware(req, res, callback) {\n    callback(req, res)\n      .then((data) =\u003e res.status(data.statusCode).json(data))\n      .catch((err) =\u003e res.status(500).json(err));\n  }\n\n  listen = (port) =\u003e this.server.listen(port);\n}\n\nexport default new Server();\n```\n\nTo add a route to the server it is necessary to create a file for building routes by calling an option from the ExpressSwagger property and thus passing its parameters, that way the API documentation and route will already be created, see:\n\n**Note:** The parameter object follows the same structure pattern as [swagger.js documentation](https://swagger.io/docs/specification/describing-parameters/) (openapi: 3.0.0).\n\n```js\nimport ExpressSwagger from '../../dist/index';\nimport { specification } from '../configs/swagger';\nimport Return from '../models/Return';\n\nexport default class ExampleController {\n  static setRoutes() {\n    ExpressSwagger.Server.addRoute({\n      auth: true,\n      method: 'GET',\n      path: '/example',\n      tags: ['Example'],\n      summary: 'Example Controller',\n      security: [specification.components.securitySchemes],\n      responses: specification.components.responses,\n      handler: async (req) =\u003e {\n        return new Return(200, 'OK', {\n          date: new Date(),\n        });\n      },\n    });\n\n    ExpressSwagger.Server.addRoute({\n      auth: true,\n      method: 'GET',\n      path: '/example/:text',\n      tags: ['Example'],\n      summary: 'Example Controller',\n      security: [specification.components.securitySchemes],\n      responses: specification.components.responses,\n      parameters: [\n        {\n          in: 'path',\n          required: true,\n          name: 'text',\n          schema: {\n            type: 'string',\n          },\n          description: 'Text to print in the response',\n        },\n      ],\n      handler: async (req) =\u003e {\n        return new Return(200, 'OK', {\n          date: new Date(),\n          text: req.params.text,\n        });\n      },\n    });\n  }\n}\n```\n\n## 🔹 Contributors\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://github.com/donatocardoso\"\u003e\n        \u003cimg src=\"https://avatars.githubusercontent.com/u/28939485?v=3\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\n        \u003csub\u003e🥇 \u003cb\u003eDonato C. Ávila\u003c/b\u003e\u003c/sub\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://github.com/ThiagoOliveira001\"\u003e\n        \u003cimg src=\"https://avatars.githubusercontent.com/u/18088052?v=3\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\n        \u003csub\u003e\u003cb\u003eThiago S. Oliveira\u003c/b\u003e\u003c/sub\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003ctable\u003e\n\n## 🔹 License\n\n[MIT](LICENSE)\n\n[badge-branches]: ./__tests__/badges/badge-branches.svg\n[badge-functions]: ./__tests__/badges/badge-functions.svg\n[badge-lines]: ./__tests__/badges/badge-lines.svg\n[badge-statements]: ./__tests__/badges/badge-statements.svg\n[npm-image]: https://img.shields.io/npm/v/express-swagger-delta.svg\n[npm-url]: https://npmjs.org/package/express-swagger-delta\n[downloads-image]: https://img.shields.io/npm/dm/express-swagger-delta.svg\n[downloads-url]: https://npmjs.org/package/express-swagger-delta\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdonatocardoso%2Fexpress-swagger-delta","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdonatocardoso%2Fexpress-swagger-delta","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdonatocardoso%2Fexpress-swagger-delta/lists"}