{"id":13451872,"url":"https://github.com/scottie1984/swagger-ui-express","last_synced_at":"2025-05-16T01:00:25.725Z","repository":{"id":10167543,"uuid":"64787180","full_name":"scottie1984/swagger-ui-express","owner":"scottie1984","description":"Adds middleware to your express app to serve the Swagger UI bound to your Swagger document. This acts as living documentation for your API hosted from within your app.","archived":false,"fork":false,"pushed_at":"2025-01-25T15:56:04.000Z","size":10932,"stargazers_count":1465,"open_issues_count":48,"forks_count":229,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-05-09T00:55:15.710Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"HTML","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/scottie1984.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-08-02T19:41:34.000Z","updated_at":"2025-05-07T08:45:17.000Z","dependencies_parsed_at":"2023-01-13T15:46:46.374Z","dependency_job_id":"f5b4ad53-f799-4086-821d-6e2d251f2029","html_url":"https://github.com/scottie1984/swagger-ui-express","commit_stats":{"total_commits":155,"total_committers":49,"mean_commits":3.163265306122449,"dds":0.7483870967741936,"last_synced_commit":"0d0c78845c7a24e3f6cfc2023ec16a0d0b6278e9"},"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottie1984%2Fswagger-ui-express","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottie1984%2Fswagger-ui-express/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottie1984%2Fswagger-ui-express/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottie1984%2Fswagger-ui-express/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/scottie1984","download_url":"https://codeload.github.com/scottie1984/swagger-ui-express/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254448578,"owners_count":22072764,"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":[],"created_at":"2024-07-31T07:01:05.358Z","updated_at":"2025-05-16T01:00:25.688Z","avatar_url":"https://github.com/scottie1984.png","language":"HTML","funding_links":[],"categories":["HTML","JavaScript"],"sub_categories":[],"readme":"# Swagger UI Express\n\n| Statements                  | Branches                | Functions                 | Lines                |\n| --------------------------- | ----------------------- | ------------------------- | -------------------- |\n| ![Statements](https://img.shields.io/badge/Coverage-89.87%25-yellow.svg) | ![Branches](https://img.shields.io/badge/Coverage-78.57%25-red.svg) | ![Functions](https://img.shields.io/badge/Coverage-91.67%25-brightgreen.svg) | ![Lines](https://img.shields.io/badge/Coverage-89.74%25-yellow.svg)    |\n\nThis module allows you to serve auto-generated [swagger-ui](https://swagger.io/tools/swagger-ui/) generated API docs from express, based on a `swagger.json` file. The result is living documentation for your API hosted from your API server via a route.\n\nSwagger version is pulled from npm module swagger-ui-dist. Please use a lock file or specify the version of swagger-ui-dist you want to ensure it is consistent across environments.\n\nYou may be also interested in:\n\n* [swagger-jsdoc](https://github.com/Surnet/swagger-jsdoc): Allows you to markup routes\nwith jsdoc comments. It then produces a full swagger yml config dynamically, which you can pass to this module to produce documentation. See below under the usage section for more info.\n* [swagger tools](https://github.com/swagger-api): Various tools, including swagger editor, swagger code gen etc.\n\n## Usage\n\nInstall using npm:\n\n```bash\n$ npm install swagger-ui-express\n```\n\nExpress setup `app.js`\n```javascript\nconst express = require('express');\nconst app = express();\nconst swaggerUi = require('swagger-ui-express');\nconst swaggerDocument = require('./swagger.json');\n\napp.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));\n```\n\nor if you are using Express router\n\n```javascript\nconst router = require('express').Router();\nconst swaggerUi = require('swagger-ui-express');\nconst swaggerDocument = require('./swagger.json');\n\nrouter.use('/api-docs', swaggerUi.serve);\nrouter.get('/api-docs', swaggerUi.setup(swaggerDocument));\n```\n\nOpen http://`\u003capp_host\u003e`:`\u003capp_port\u003e`/api-docs in your browser to view the documentation.\n\nIf you want to set up routing based on the swagger document checkout [swagger-express-router](https://www.npmjs.com/package/swagger-express-router)\n\n### [swagger-jsdoc](https://www.npmjs.com/package/swagger-jsdoc)\n\nIf you are using swagger-jsdoc simply pass the swaggerSpec into the setup function:\n\n```javascript\n// Initialize swagger-jsdoc -\u003e returns validated swagger spec in json format\nconst swaggerSpec = swaggerJSDoc(options);\n\napp.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));\n```\n\n### Swagger Explorer\n\nBy default the Swagger Explorer bar is hidden, to display it pass true as the 'explorer' property of the options to the setup function:\n\n```javascript\nconst express = require('express');\nconst app = express();\nconst swaggerUi = require('swagger-ui-express');\nconst swaggerDocument = require('./swagger.json');\n\nvar options = {\n  explorer: true\n};\n\napp.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, options));\n```\n\n### Custom swagger options\n\nTo pass custom options e.g. validatorUrl, to the SwaggerUi client pass an object as the 'swaggerOptions' property of the options to the setup function:\n\n```javascript\nconst express = require('express');\nconst app = express();\nconst swaggerUi = require('swagger-ui-express');\nconst swaggerDocument = require('./swagger.json');\n\nvar options = {\n  swaggerOptions: {\n    validatorUrl: null\n  }\n};\n\napp.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, options));\n```\n\nFor all the available options, refer to [Swagger UI Configuration](https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md)\n\n### Custom CSS styles\n\nTo customize the style of the swagger page, you can pass custom CSS as the 'customCss' property of the options to the setup function.\n\nE.g. to hide the swagger header:\n\n```javascript\nconst express = require('express');\nconst app = express();\nconst swaggerUi = require('swagger-ui-express');\nconst swaggerDocument = require('./swagger.json');\n\nvar options = {\n  customCss: '.swagger-ui .topbar { display: none }'\n};\n\napp.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, options));\n```\n\n### Custom CSS styles from Url\n\nYou can also pass the url to a custom css file, the value must be the public url of the file and can be relative or absolute to the swagger path.\n\n```javascript\nconst express = require('express');\nconst app = express();\nconst swaggerUi = require('swagger-ui-express');\nconst swaggerDocument = require('./swagger.json');\n\nvar options = {\n  customCssUrl: '/custom.css'\n};\n\napp.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, options));\n```\n\nYou can also pass an array of css urls to load multiple css files.\n\n```javascript\nconst express = require('express');\nconst app = express();\nconst swaggerUi = require('swagger-ui-express');\nconst swaggerDocument = require('./swagger.json');\n\nvar options = {\n  customCssUrl: [\n    '/custom.css',\n    'https://example.com/other-custom.css'\n  ]\n};\n\napp.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, options));\n```\n\n### Custom JS\n\nIf you would like to have full control over your HTML you can provide your own javascript file, value accepts absolute or relative path. Value must be the public url of the js file.\n\n```javascript\nconst express = require('express');\nconst app = express();\nconst swaggerUi = require('swagger-ui-express');\nconst swaggerDocument = require('./swagger.json');\n\nvar options = {\n  customJs: '/custom.js'\n};\n\napp.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, options));\n```\n\nYou can also pass an array of js urls to load multiple js files.\n\n```javascript\nconst express = require('express');\nconst app = express();\nconst swaggerUi = require('swagger-ui-express');\nconst swaggerDocument = require('./swagger.json');\n\nvar options = {\n  customJs: [\n    '/custom.js',\n    'https://example.com/other-custom.js'\n  ]\n};\n\napp.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, options));\n```\n\nIt is also possible to add inline javascript, either as string or array of string.\n\n```javascript\nconst express = require('express');\nconst app = express();\nconst swaggerUi = require('swagger-ui-express');\nconst swaggerDocument = require('./swagger.json');\n\nvar options = {\n  customJsStr: 'console.log(\"Hello World\")'\n};\n\napp.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, options));\n```\n\n```javascript\nconst express = require('express');\nconst app = express();\nconst swaggerUi = require('swagger-ui-express');\nconst swaggerDocument = require('./swagger.json');\n\nvar options = {\n  customJsStr: [\n    'console.log(\"Hello World\")',\n    `\n    var x = 1\n    console.log(x)\n    `\n  ]\n};\n\napp.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, options));\n```\n\n### Load swagger from url\n\nTo load your swagger from a url instead of injecting the document, pass `null` as the first parameter, and pass the relative or absolute URL as the 'url' property to 'swaggerOptions' in the setup function.\n\n```javascript\nconst express = require('express');\nconst app = express();\nconst swaggerUi = require('swagger-ui-express');\n\nvar options = {\n  swaggerOptions: {\n    url: 'http://petstore.swagger.io/v2/swagger.json'\n  }\n}\n\napp.use('/api-docs', swaggerUi.serve, swaggerUi.setup(null, options));\n```\n\nTo load multiple swagger documents from urls as a dropdown in the explorer bar, pass an array of object with `name` and `url` to 'urls' property to 'swaggerOptions' in the setup function.\n\n```javascript\nconst express = require('express');\nconst app = express();\nconst swaggerUi = require('swagger-ui-express');\n\nvar options = {\n  explorer: true,\n  swaggerOptions: {\n    urls: [\n      {\n        url: 'http://petstore.swagger.io/v2/swagger.json',\n        name: 'Spec1'\n      },\n      {\n        url: 'http://petstore.swagger.io/v2/swagger.json',\n        name: 'Spec2'\n      }\n    ]\n  }\n}\n\napp.use('/api-docs', swaggerUi.serve, swaggerUi.setup(null, options));\n```\n\nMake sure 'explorer' option is set to 'true' in your setup options for the dropdown to be visible.\n\n\n### Load swagger from yaml file\n\nTo load your swagger specification yaml file you need to use a module able to convert yaml to json; for instance `yaml`.\n\n    npm install yaml\n\n```javascript\nconst express = require('express');\nconst app = express();\nconst swaggerUi = require('swagger-ui-express');\nconst fs = require(\"fs\")\nconst YAML = require('yaml')\n\nconst file  = fs.readFileSync('./swagger.yaml', 'utf8')\nconst swaggerDocument = YAML.parse(file)\n\napp.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));\n```\n\n\n### Modify swagger file on the fly before load\n\nTo dynamically set the host, or any other content, in the swagger file based on the incoming request object you may pass the json via the req object; to achieve this just do not pass the the swagger json to the setup function and it will look for `swaggerDoc` in the `req` object.\n\n```javascript\nconst express = require('express');\nconst app = express();\nconst swaggerUi = require('swagger-ui-express');\nconst swaggerDocument = require('./swagger.json');\n\nvar options = {}\n\napp.use('/api-docs', function(req, res, next){\n    swaggerDocument.host = req.get('host');\n    req.swaggerDoc = swaggerDocument;\n    next();\n}, swaggerUi.serveFiles(swaggerDocument, options), swaggerUi.setup());\n```\n\n### Two swagger documents\n\nTo run 2 swagger ui instances with different swagger documents, use the serveFiles function instead of the serve function. The serveFiles function has the same signature as the setup function.\n\n```javascript\nconst express = require('express');\nconst app = express();\nconst swaggerUi = require('swagger-ui-express');\nconst swaggerDocumentOne = require('./swagger-one.json');\nconst swaggerDocumentTwo = require('./swagger-two.json');\n\nvar options = {}\n\napp.use('/api-docs-one', swaggerUi.serveFiles(swaggerDocumentOne, options), swaggerUi.setup(swaggerDocumentOne));\n\napp.use('/api-docs-two', swaggerUi.serveFiles(swaggerDocumentTwo, options), swaggerUi.setup(swaggerDocumentTwo));\n\napp.use('/api-docs-dynamic', function(req, res, next){\n  req.swaggerDoc = swaggerDocument;\n  next();\n}, swaggerUi.serveFiles(), swaggerUi.setup());\n```\n\n### Link to Swagger document\n\nTo render a link to the swagger document for downloading within the swagger ui - then serve the swagger doc as an endpoint and use the url option to point to it:\n\n```javascript\nconst express = require('express');\nconst app = express();\nconst swaggerUi = require('swagger-ui-express');\nconst swaggerDocument = require('./swagger.json');\n\nvar options = {\n    swaggerOptions: {\n        url: \"/api-docs/swagger.json\",\n    },\n}\napp.get(\"/api-docs/swagger.json\", (req, res) =\u003e res.json(swaggerDocument));\napp.use('/api-docs', swaggerUi.serveFiles(null, options), swaggerUi.setup(null, options));\n```\n\n\n## Requirements\n\n* Node v0.10.32 or above\n* Express 4 or above\n\n## Testing\n\n* Install phantom\n* `npm install`\n* `npm test`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscottie1984%2Fswagger-ui-express","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscottie1984%2Fswagger-ui-express","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscottie1984%2Fswagger-ui-express/lists"}