Generate an OpenAPI/Swagger definition from inline comments.
npm install swagger-inline> Warning
> 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, fastify-swagger).
Generate an OpenAPI/Swagger definition from inline comments.
 

- Installation
- Usage
- CLI
- Library
- Examples
```
npm install swagger-inline --save-dev
``
npx swagger-inline [--base] [--format]
#### Example
`bash`
npx swagger-inline "./*.js" --base 'swaggerBase.json' > api.json
#### Options
The inputGlobs argument is a list of files, or globs, to search for Swagger/OAS comments.
- base: Base API specification to extend. Requiredformat
- : Output filetype: .json or .yaml (default: .json)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.
``
swaggerInline([inputGlobs...], options) => Promise => json | yaml
#### Example
`js
const swaggerInline = require('swagger-inline');
swaggerInline(['src//.js', 'test//.js'], {
base: 'swaggerBase.json',
}).then(generatedSwagger => {
/ ... /
});
`
#### Available options
- base: Base specification to extend. Requiredformat
- : Output filetype: .json or .yaml (default: .json)ignore
- : An array of globs for files to ignore. (default: ['node_modules//', 'bower_modules//'],logger
- : Function called for logging. (default: empty closure)metadata
- : Add additional annotations to the Swagger file, prefixed with x-si.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.ignoreErrors
- : Ignore errors due to image files or unknown file types when parsing files. (default: false)
#### 1) Create a project
swaggerBase.yaml
`yaml`
swagger: '2.0'
host: 'petstore.swagger.io'
basePath: '/api'
schemes: ['http']
api.js
`js
/**
* @api [get] /pets
* bodyContentType: "application/json"
* description: "Returns all pets from the system that the user has access to"
* responses:
* "200":
* description: "A list of pets."
* schema:
* type: "String"
*/
api.route('/pets', function () {
/ Pet code 😺 /
});
/**
* @schema Pet
* required:
* - id
* - name
* properties:
* id:
* type: integer
* format: int64
* name:
* type: string
* tag:
* type: string
*/
// some schema related function
`
#### 2) Run Command
`bash`
swagger-inline './*.js' --base './swaggerBase.yaml'
Output:
`yaml`
swagger: '2.0'
host: petstore.swagger.io
basePath: /api
schemes:
- http
paths:
/pets:
get:
description: Returns all pets from the system that the user has access to
responses:
'200':
description: A list of pets.
schema:
type: String
components:
schemas:
Pet:
required:
- id
- name
properties:
id:
type: integer
format: int64
name:
type: string
tag:
type: string
With 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.
`js
/**
* @api [get] /pets
* scope: public
* description: "Returns all pets from the system that the user has access to"
* responses:
* "200":
* description: "A list of pets."
* schema:
* type: "String"
*/
/**
* @api [post] /pets
* description: "Creates a new pet
* responses:
* "200":
* description: "The created pet."
*/
`
Now 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.
Defining 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.
Here's a simple example:
``
(query) limit=5* {Integer:int32} Amount returned
It has a lot of info packed into a short space:
- The parameter type: querylimit
- The name of the parameter: *
- The default value: 5
- A flag to indicate that the parameter is required: Integer
- The type: int32
- The format of the type: Amount returned
- The parameter description:
Almost all of these are optional — you can write something as concise as this:
```
(query) limit