{"id":14986503,"url":"https://github.com/surnet/swagger-jsdoc","last_synced_at":"2025-05-12T13:11:58.419Z","repository":{"id":33328440,"uuid":"36973196","full_name":"Surnet/swagger-jsdoc","owner":"Surnet","description":"Generates swagger/openapi specification based on jsDoc comments and YAML files.","archived":false,"fork":false,"pushed_at":"2025-04-27T22:06:35.000Z","size":3059,"stargazers_count":1737,"open_issues_count":39,"forks_count":231,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-05-12T13:11:49.845Z","etag":null,"topics":["jsdoc","openapi","swagger","swagger-jsdoc"],"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/Surnet.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"zenodo":null}},"created_at":"2015-06-06T08:36:18.000Z","updated_at":"2025-05-09T15:24:59.000Z","dependencies_parsed_at":"2024-06-18T11:09:12.167Z","dependency_job_id":"e2d53525-ac1d-4d84-9a26-d339b8938531","html_url":"https://github.com/Surnet/swagger-jsdoc","commit_stats":{"total_commits":375,"total_committers":73,"mean_commits":5.136986301369863,"dds":0.72,"last_synced_commit":"2325600ec6f2a40930fd7afc272a491bbab5d93c"},"previous_names":[],"tags_count":82,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Surnet%2Fswagger-jsdoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Surnet%2Fswagger-jsdoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Surnet%2Fswagger-jsdoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Surnet%2Fswagger-jsdoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Surnet","download_url":"https://codeload.github.com/Surnet/swagger-jsdoc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253745175,"owners_count":21957318,"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":["jsdoc","openapi","swagger","swagger-jsdoc"],"created_at":"2024-09-24T14:13:01.429Z","updated_at":"2025-05-12T13:11:58.360Z","avatar_url":"https://github.com/Surnet.png","language":"JavaScript","readme":"# swagger-jsdoc\n\nThis library reads your [JSDoc](https://jsdoc.app/)-annotated source code and generates an [OpenAPI (Swagger) specification](https://swagger.io/specification/).\n\n[![npm Downloads](https://img.shields.io/npm/dm/swagger-jsdoc.svg)](https://www.npmjs.com/package/swagger-jsdoc)\n![CI](https://github.com/Surnet/swagger-jsdoc/workflows/CI/badge.svg)\n\n## Getting started\n\nImagine having API files like these:\n\n```javascript\n/**\n * @openapi\n * /:\n *   get:\n *     description: Welcome to swagger-jsdoc!\n *     responses:\n *       200:\n *         description: Returns a mysterious string.\n */\napp.get('/', (req, res) =\u003e {\n  res.send('Hello World!');\n});\n```\n\nThe library will take the contents of `@openapi` (or `@swagger`) with the following configuration:\n\n```javascript\nconst swaggerJsdoc = require('swagger-jsdoc');\n\nconst options = {\n  definition: {\n    openapi: '3.0.0',\n    info: {\n      title: 'Hello World',\n      version: '1.0.0',\n    },\n  },\n  apis: ['./src/routes*.js'], // files containing annotations as above\n};\n\nconst openapiSpecification = swaggerJsdoc(options);\n```\n\nThe resulting `openapiSpecification` will be a [swagger tools](https://swagger.io/tools/)-compatible (and validated) specification.\n\n![swagger-jsdoc example screenshot](./docs/screenshot.png)\n\n## System requirements\n\n- Node.js 12.x or higher\n\nYou are viewing `swagger-jsdoc` v6 which is published in CommonJS module system.\n\n## Installation\n\n```bash\nnpm install swagger-jsdoc --save\n```\n\nOr\n\n```bash\nyarn add swagger-jsdoc\n```\n\n## Supported specifications\n\n- OpenAPI 3.x\n- Swagger 2\n- AsyncAPI 2.0\n\n## Validation of swagger docs\n\nBy default `swagger-jsdoc` tries to parse all docs to it's best capabilities. If you'd like to you can instruct an Error to be thrown instead if validation failed by setting the options flag `failOnErrors` to `true`. This is for instance useful if you want to verify that your swagger docs validate using a unit test.\n\n```javascript\nconst swaggerJsdoc = require('swagger-jsdoc');\n\nconst options = {\n  failOnErrors: true, // Whether or not to throw when parsing errors. Defaults to false.\n  definition: {\n    openapi: '3.0.0',\n    info: {\n      title: 'Hello World',\n      version: '1.0.0',\n    },\n  },\n  apis: ['./src/routes*.js'],\n};\n\nconst openapiSpecification = swaggerJsdoc(options);\n```\n\n## Documentation\n\nClick on the version you are using for further details:\n\n- [7.x](https://github.com/Surnet/swagger-jsdoc/tree/v7/docs)\n- [6.x](https://github.com/Surnet/swagger-jsdoc/tree/v6/docs)\n- [5.x](https://github.com/Surnet/swagger-jsdoc/tree/v5)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsurnet%2Fswagger-jsdoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsurnet%2Fswagger-jsdoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsurnet%2Fswagger-jsdoc/lists"}