Skip to content

Generate an OpenAPI/Swagger definition from inline comments.

License

Notifications You must be signed in to change notification settings

readmeio/swagger-inline

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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.

npm Build

Installation

npm install swagger-inline --save-dev

Usage

CLI

npx swagger-inline [--base] [--format] <inputGlobs ...>

Example

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.

Library

swaggerInline([inputGlobs...], options) => Promise => json | yaml

Example

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

Standard usage

1) Create a project

swaggerBase.yaml

swagger: '2.0'
host: 'petstore.swagger.io'
basePath: '/api'
schemes: ['http']

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

swagger-inline './*.js' --base './swaggerBase.yaml'

Output:

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

Scoped compilations

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.

/**
 * @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.

Parameter shorthand declarations

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