{"id":28558960,"url":"https://github.com/readmeio/swagger-inline","last_synced_at":"2025-06-10T08:35:50.689Z","repository":{"id":10389265,"uuid":"65591126","full_name":"readmeio/swagger-inline","owner":"readmeio","description":"Generate an OpenAPI/Swagger definition from inline comments.","archived":false,"fork":false,"pushed_at":"2024-08-30T15:54:42.000Z","size":2915,"stargazers_count":146,"open_issues_count":1,"forks_count":37,"subscribers_count":22,"default_branch":"main","last_synced_at":"2025-05-30T01:52:16.851Z","etag":null,"topics":["openapi","swagger"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/readmeio.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-13T00:29:50.000Z","updated_at":"2025-04-30T01:55:39.000Z","dependencies_parsed_at":"2023-10-05T02:41:24.119Z","dependency_job_id":"25271ff4-9c5b-49c5-be23-2db298f0f435","html_url":"https://github.com/readmeio/swagger-inline","commit_stats":{"total_commits":429,"total_committers":22,"mean_commits":19.5,"dds":0.655011655011655,"last_synced_commit":"75ba24d44190f82c3218032b8114c8ab4bbf53e4"},"previous_names":[],"tags_count":42,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/readmeio%2Fswagger-inline","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/readmeio%2Fswagger-inline/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/readmeio%2Fswagger-inline/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/readmeio%2Fswagger-inline/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/readmeio","download_url":"https://codeload.github.com/readmeio/swagger-inline/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/readmeio%2Fswagger-inline/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259039474,"owners_count":22796840,"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":["openapi","swagger"],"created_at":"2025-06-10T08:35:49.438Z","updated_at":"2025-06-10T08:35:50.593Z","avatar_url":"https://github.com/readmeio.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e **Warning**\n\u003e This library is no longer being actively maintained (except for critical security fixes) nor is it recommended. We recommend using JSON Schema-based, strongly-typed tools to generate your OpenAPI definition (e.g., [FastAPI](https://github.com/tiangolo/fastapi), [`fastify-swagger`](https://github.com/fastify/fastify-swagger)).\n\n# swagger-inline\n\nGenerate an OpenAPI/Swagger definition from inline comments.\n\n[![npm](https://img.shields.io/npm/v/swagger-inline)](https://npm.im/swagger-inline) [![Build](https://github.com/readmeio/swagger-inline/workflows/CI/badge.svg)](https://github.com/readmeio/swagger-inline)\n\n[![](https://raw.githubusercontent.com/readmeio/.github/main/oss-header.png)](https://readme.io)\n\n- [Installation](#installation)\n- [Usage](#usage)\n  - [CLI](#cli)\n  - [Library](#library)\n- [Examples](#examples)\n\n## Installation\n\n```\nnpm install swagger-inline --save-dev\n```\n\n## Usage\n\n### CLI\n\n```\nnpx swagger-inline [--base] [--format] \u003cinputGlobs ...\u003e\n```\n\n#### Example\n\n```bash\nnpx swagger-inline \"./*.js\" --base 'swaggerBase.json' \u003e api.json\n```\n\n#### Options\n\nThe `inputGlobs` argument is a list of files, or globs, to search for Swagger/OAS comments.\n\n- `base`: Base API specification to extend. **Required**\n- `format`: Output filetype: `.json` or `.yaml` (default: `.json`)\n- `scope`: Matches the scope field defined in each API. For example, if `--scope public` is supplied, all operations will be generated, if `--scope private`, only those operations that have a `scope: private` declaration will be included.\n\n### Library\n\n```\nswaggerInline([inputGlobs...], options) =\u003e Promise =\u003e json | yaml\n```\n\n#### Example\n\n```js\nconst swaggerInline = require('swagger-inline');\n\nswaggerInline(['src/**/*.js', 'test/**/*.js'], {\n  base: 'swaggerBase.json',\n}).then(generatedSwagger =\u003e {\n  /* ... */\n});\n```\n\n#### Available options\n\n- `base`: Base specification to extend. **Required**\n- `format`: Output filetype: `.json` or `.yaml` (default: `.json`)\n- `ignore`: An array of globs for files to ignore. (default: `['node_modules/**/*', 'bower_modules/**/*']`,\n- `logger`: Function called for logging. (default: empty closure)\n- `metadata`: Add additional annotations to the Swagger file, prefixed with `x-si`.\n- `scope`: Matches the scope field defined in each API. For example, if `--scope public` is supplied, all operations will be generated, if `--scope private`, only those operations that have a `scope: private` declaration will be included.\n- `ignoreErrors`: Ignore errors due to image files or unknown file types when parsing files. (default: `false`)\n\n## Examples\n\n### Standard usage\n\n#### 1) Create a project\n\n`swaggerBase.yaml`\n\n```yaml\nswagger: '2.0'\nhost: 'petstore.swagger.io'\nbasePath: '/api'\nschemes: ['http']\n```\n\n`api.js`\n\n```js\n/**\n * @api [get] /pets\n * bodyContentType: \"application/json\"\n * description: \"Returns all pets from the system that the user has access to\"\n * responses:\n *   \"200\":\n *     description: \"A list of pets.\"\n *     schema:\n *       type: \"String\"\n */\n\napi.route('/pets', function () {\n  /* Pet code 😺 */\n});\n\n/**\n * @schema Pet\n * required:\n *   - id\n *   - name\n * properties:\n *   id:\n *     type: integer\n *     format: int64\n *   name:\n *     type: string\n *   tag:\n *     type: string\n */\n\n// some schema related function\n```\n\n#### 2) Run Command\n\n```bash\nswagger-inline './*.js' --base './swaggerBase.yaml'\n```\n\n**Output:**\n\n```yaml\nswagger: '2.0'\nhost: petstore.swagger.io\nbasePath: /api\nschemes:\n  - http\npaths:\n  /pets:\n    get:\n      description: Returns all pets from the system that the user has access to\n      responses:\n        '200':\n          description: A list of pets.\n          schema:\n            type: String\ncomponents:\n  schemas:\n    Pet:\n      required:\n        - id\n        - name\n      properties:\n        id:\n          type: integer\n          format: int64\n        name:\n          type: string\n        tag:\n          type: string\n```\n\n### Scoped compilations\n\nWith the `--scope` parameter, you can compile your files based on a specific target that you define within your inline comments. For example, we have an API with a `GET /pets` and `POST /pets` but only the `GET` operation is public. We can add `scope: public` to our `GET` operation documentation to tell `swagger-inline` what scope it's set under.\n\n```js\n/**\n * @api [get] /pets\n * scope: public\n * description: \"Returns all pets from the system that the user has access to\"\n * responses:\n *   \"200\":\n *     description: \"A list of pets.\"\n *     schema:\n *       type: \"String\"\n */\n\n/**\n * @api [post] /pets\n * description: \"Creates a new pet\n * responses:\n *   \"200\":\n *     description: \"The created pet.\"\n */\n```\n\nNow when you run `swagger-inline`, you can supply `--scope public` and only the `GET /pets` operation will be picked up. Omit `--scope public` and everything will be picked up.\n\n### Parameter shorthand declarations\n\nDefining a parameter in OpenAPI can be verbose, so you can define parameters via shorthands. If you require something more complex, you can use the [full OpenAPI parameter syntax](https://swagger.io/docs/specification/describing-parameters/).\n\nHere's a simple example:\n\n```\n(query) limit=5* {Integer:int32} Amount returned\n```\n\nIt has a lot of info packed into a short space:\n\n- The parameter type: `query`\n- The name of the parameter: `limit`\n- The default value: 5\n- A flag to indicate that the parameter is required: `*`\n- The type: `Integer`\n- The format of the type: `int32`\n- The parameter description: `Amount returned`\n\nAlmost all of these are optional — you can write something as concise as this:\n\n```\n(query) limit\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freadmeio%2Fswagger-inline","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freadmeio%2Fswagger-inline","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freadmeio%2Fswagger-inline/lists"}