swagger-inline
v7.0.1
Published
Generate an OpenAPI/Swagger definition from inline comments.
Downloads
60,473
Readme
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
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. 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 ascope: 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. 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 withx-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 ascope: 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