> 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).

swagger-inline

Generate an OpenAPI/Swagger definition from inline comments.

 


- Installation
- Usage
- CLI
- Library
- Examples

Installation

``
npm install swagger-inline --save-dev
`

Usage

$3

`
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. Required
- format: 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.

$3

`
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. Required
- format: 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)

Examples

$3

#### 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
`

$3

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.

$3

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: query
- The name of the parameter: limit
- The default value: 5
- A flag to indicate that the parameter is required: *
- The type: Integer
- The format of the type: int32
- The parameter description: Amount returned

Almost all of these are optional — you can write something as concise as this:

`
(query) limit
``