openapi-doc/README.md

Programmatically builds an Open API (Swagger 2.0) document as an Express endpoint so that the documentation and source can live together in one place. It is like annotating an Express endpoint. Later, the API can be bound to Express.

# openapi-doc

Programmatically builds an Open API (Swagger 2.0) document as an Express endpoint so that the documentation and source can live together in one place. It is like annotating an Express endpoint. Later, the API can be bound to Express.

## Features

* Programmatically define an Open API (Swagger 2.0) API.
* Generates a syntactically correct Swagger API JSON document from source.
* Swagger API document can be served via Express.

## Install

`npm install --save openapi-doc`

# API Reference

Open API documentation for node.js and Express.js

**Example** *(Quick start)*  
```javascript
    const Swagger = require('openapi-doc');
    const swagger = new Swagger();
    swagger.info('My API', '1.0', 'This is *API*');

    // describe API endpoint and action
    swagger.get('/logs')
        .operationId('getLogs')
        .tag('logging')
        .summary('Gets an array of logs.')
        .response(200)
        .action((req, res) => {
            res.sendStatus(200);
        });
```
**Example** *(Bind API to Express endpoint)*  
```javascript
    const prefix = '/api';
    Swagger.forEachAction(swagger, (verb, path) => {
        const endpoint = uriUtils.oasPathToExpress(prefix + path);
        // express app
        app[verb](
            endpoint,
            Swagger.actionMiddleware(swagger, verb, path)
        );
    });
```
**Example** *(Apply security)*  
```javascript
    const prefix = '/api';
    swagger.securityDefinition(
        'basicAuth', {
            type: 'basic',
            description: 'Username and password',
        },
        (req) => {
            return true;
        }
    );
    Swagger.forEachAction(swagger, (verb, path) => {
        const endpoint = uriUtils.oasPathToExpress(prefix + path);
        // express app
        app[verb](
            endpoint,
            Swagger.securityMiddleware(swagger, verb, path),
            Swagger.actionMiddleware(swagger, verb, path)
        );
    });
```
**Example** *(Bind generated Swagger API document to Express endpoint)*  
```javascript
    app.get('/api-doc', function (req, resp) {
        resp.send(swagger.apidoc());
    });
```
<a name="module_openapi-doc..Swagger"></a>

### openapi-doc~Swagger
**Kind**: inner class of [<code>openapi-doc</code>](#module_openapi-doc)  

* [~Swagger](#module_openapi-doc..Swagger)
    * [new Swagger()](#new_module_openapi-doc..Swagger_new)
    * _instance_
        * [.securityHandlers](#module_openapi-doc..Swagger+securityHandlers) ⇒ <code>object</code>
        * [.actions](#module_openapi-doc..Swagger+actions) ⇒ <code>object</code>
        * [.info(title, version, description)](#module_openapi-doc..Swagger+info) ⇒ <code>Swagger</code>
        * [.host(name)](#module_openapi-doc..Swagger+host) ⇒ <code>Swagger</code>
        * [.license(name)](#module_openapi-doc..Swagger+license) ⇒ <code>Swagger</code>
        * [.contact(name, [email], [url])](#module_openapi-doc..Swagger+contact) ⇒ <code>Swagger</code>
        * [.termsOfService(terms)](#module_openapi-doc..Swagger+termsOfService) ⇒ <code>Swagger</code>
        * [.basePath(path)](#module_openapi-doc..Swagger+basePath) ⇒ <code>Swagger</code>
        * [.globalSchemes(schemes)](#module_openapi-doc..Swagger+globalSchemes) ⇒ <code>Swagger</code>
        * [.schemes(schemes)](#module_openapi-doc..Swagger+schemes) ⇒ <code>Swagger</code>
        * [.securityDefinition(name, options, handler)](#module_openapi-doc..Swagger+securityDefinition) ⇒ <code>Swagger</code>
        * [.security(definitions)](#module_openapi-doc..Swagger+security) ⇒ <code>Swagger</code>
        * [.globalSecurity(definitions)](#module_openapi-doc..Swagger+globalSecurity) ⇒ <code>Swagger</code>
        * [.globalParameter(param)](#module_openapi-doc..Swagger+globalParameter) ⇒ <code>Swagger</code>
        * [.globalTag(tag)](#module_openapi-doc..Swagger+globalTag) ⇒ <code>Swagger</code>
        * [.globalResponse(name, description, [type], [isArray], [headers])](#module_openapi-doc..Swagger+globalResponse) ⇒ <code>Swagger</code>
        * [.globalExternalDocs(doc)](#module_openapi-doc..Swagger+globalExternalDocs) ⇒ <code>Swagger</code>
        * [.globalConsumes(mimeType)](#module_openapi-doc..Swagger+globalConsumes) ⇒ <code>Swagger</code>
        * [.globalProduces(mimeType)](#module_openapi-doc..Swagger+globalProduces) ⇒ <code>Swagger</code>
        * [.nosecurity()](#module_openapi-doc..Swagger+nosecurity) ⇒ <code>Swagger</code>
        * [.schema(name, spec)](#module_openapi-doc..Swagger+schema) ⇒ <code>Swagger</code>
        * [.schemas(schemas)](#module_openapi-doc..Swagger+schemas) ⇒ <code>Swagger</code>
        * [.post(path, [options])](#module_openapi-doc..Swagger+post) ⇒ <code>Swagger</code>
        * [.get(path, [options])](#module_openapi-doc..Swagger+get) ⇒ <code>Swagger</code>
        * [.put(path, [options])](#module_openapi-doc..Swagger+put) ⇒ <code>Swagger</code>
        * [.delete(path, [options])](#module_openapi-doc..Swagger+delete) ⇒ <code>Swagger</code>
        * [.patch(path, [options])](#module_openapi-doc..Swagger+patch) ⇒ <code>Swagger</code>
        * [.head(path, [options])](#module_openapi-doc..Swagger+head) ⇒ <code>Swagger</code>
        * [.options(path, [options])](#module_openapi-doc..Swagger+options) ⇒ <code>Swagger</code>
        * [.summary(summary)](#module_openapi-doc..Swagger+summary) ⇒ <code>Swagger</code>
        * [.description(description)](#module_openapi-doc..Swagger+description) ⇒ <code>Swagger</code>
        * [.operationId(name)](#module_openapi-doc..Swagger+operationId) ⇒ <code>Swagger</code>
        * [.tag(tag)](#module_openapi-doc..Swagger+tag) ⇒ <code>Swagger</code>
        * [.tags(tags)](#module_openapi-doc..Swagger+tags) ⇒ <code>Swagger</code>
        * [.body(type, description)](#module_openapi-doc..Swagger+body) ⇒ <code>Swagger</code>
        * [.parameter(param)](#module_openapi-doc..Swagger+parameter) ⇒ <code>Swagger</code>
        * [.parameters(parameters)](#module_openapi-doc..Swagger+parameters) ⇒ <code>Swagger</code>
        * [.extension(key, value)](#module_openapi-doc..Swagger+extension) ⇒ <code>Swagger</code>
        * [.consumes(mimeType)](#module_openapi-doc..Swagger+consumes) ⇒ <code>Swagger</code>
        * [.produces(mimeType, forceGlobal)](#module_openapi-doc..Swagger+produces) ⇒ <code>Swagger</code>
        * [.response(code, [description], [type], [isArray], [headers], [noValidation])](#module_openapi-doc..Swagger+response) ⇒ <code>Swagger</code>
        * [.responses(responses, [options])](#module_openapi-doc..Swagger+responses) ⇒ <code>Swagger</code>
        * [.action(handler)](#module_openapi-doc..Swagger+action) ⇒ <code>Swagger</code>
        * [.merge(swagger, [options])](#module_openapi-doc..Swagger+merge) ⇒ <code>Swagger</code>
        * [._sanitizeProperties(props)](#module_openapi-doc..Swagger+_sanitizeProperties) ⇒ <code>Swagger</code>
        * [.externalDocs(doc)](#module_openapi-doc..Swagger+externalDocs) ⇒ <code>Swagger</code>
        * [.paths(swagger, [options])](#module_openapi-doc..Swagger+paths) ⇒ <code>Swagger</code>
        * [.apidoc()](#module_openapi-doc..Swagger+apidoc) ⇒ <code>object</code>
    * _static_
        * [.forEachAction(swagger, callback)](#module_openapi-doc..Swagger.forEachAction)
        * [.actionMiddleware(swagger, verb, path)](#module_openapi-doc..Swagger.actionMiddleware) ⇒ <code>object</code>
        * [.securityMiddleware(swagger, verb, path)](#module_openapi-doc..Swagger.securityMiddleware) ⇒ <code>function</code>

<a name="new_module_openapi-doc..Swagger_new"></a>

#### new Swagger()
Construct a Swagger builder.

<a name="module_openapi-doc..Swagger+securityHandlers"></a>

#### swagger.securityHandlers ⇒ <code>object</code>
Returns all of the security handlers associated with the API endpoints.

**Kind**: instance property of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>object</code> - Map of callback functions.  
**Access**: public  
**Example**  
```js
Object.keys(swagger.securityHandlers, (key) => {
    swagger.securityHandlers[key];
});
```
<a name="module_openapi-doc..Swagger+actions"></a>

#### swagger.actions ⇒ <code>object</code>
Returns all of the actions associated with the API endpoints.

**Kind**: instance property of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>object</code> - Map of [path][verb].  
**Access**: public  
<a name="module_openapi-doc..Swagger+info"></a>

#### swagger.info(title, version, description) ⇒ <code>Swagger</code>
Adds information for the API.

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| title | <code>string</code> | the title of the API |
| version | <code>string</code> | the version of the API |
| description | <code>string</code> | the description of the API |

**Example**  
```js
swagger.info('My API', '1.0', 'This is *API*');
```
<a name="module_openapi-doc..Swagger+host"></a>

#### swagger.host(name) ⇒ <code>Swagger</code>
Sets the host for the API

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| name | <code>string</code> | the hostname of the API, e.g. 'localhost' |

<a name="module_openapi-doc..Swagger+license"></a>

#### swagger.license(name) ⇒ <code>Swagger</code>
Sets the license for the API

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| name | <code>string</code> | the license name |

<a name="module_openapi-doc..Swagger+contact"></a>

#### swagger.contact(name, [email], [url]) ⇒ <code>Swagger</code>
Sets the contact name and email

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| name | <code>string</code> | the contact name |
| [email] | <code>string</code> | the contact email |
| [url] | <code>string</code> | the contact url |

<a name="module_openapi-doc..Swagger+termsOfService"></a>

#### swagger.termsOfService(terms) ⇒ <code>Swagger</code>
Sets the terms of service for the API

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| terms | <code>string</code> | the terms of service |

<a name="module_openapi-doc..Swagger+basePath"></a>

#### swagger.basePath(path) ⇒ <code>Swagger</code>
Sets the API base path

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| path | <code>string</code> | the API base path |

<a name="module_openapi-doc..Swagger+globalSchemes"></a>

#### swagger.globalSchemes(schemes) ⇒ <code>Swagger</code>
Sets the schemes for the API

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| schemes | <code>array</code> | An array of http schemes |

<a name="module_openapi-doc..Swagger+schemes"></a>

#### swagger.schemes(schemes) ⇒ <code>Swagger</code>
Sets the schemes for the method

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| schemes | <code>array</code> | An array of http schemes |

<a name="module_openapi-doc..Swagger+securityDefinition"></a>

#### swagger.securityDefinition(name, options, handler) ⇒ <code>Swagger</code>
Adds a Security Definition.

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| name | <code>string</code> | the name of the security definition |
| options | <code>object</code> | The options for this security definition. See: http://swagger.io/specification/#securityDefinitionsObject |
| handler | <code>customAuthentication</code> | The middleware handler function. security definition. |

**Example**  
```javascript
swagger.securityDefinition(
    'basicAuth',
    {
         type: 'basic',
         description: 'Requires username:password'
    },
    (req) => {
         return true;
    }
});
// Assign security definition globally.
swagger.security('basicAuth');
```
<a name="module_openapi-doc..Swagger+security"></a>

#### swagger.security(definitions) ⇒ <code>Swagger</code>
Adds a Security Requirement to the current method.  If `definitions` is empty,
then then no security is applied.  The `definitions` can be a `string`, an
array of `string`, or an array of `object`.  If `definitions` is an array
of `object`, then it must be an array of security
Requirement Objects, e.g. `[{apikey: []}]`.

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| definitions | <code>array</code> | An array of the Security Definition to apply. |

<a name="module_openapi-doc..Swagger+globalSecurity"></a>

#### swagger.globalSecurity(definitions) ⇒ <code>Swagger</code>
Adds a Security Requirement globally for the API.  If `definitions` is empty,
then then no security is applied.  The `definitions` can be a `string`, an
array of `string`, or an array of `object`.  If `definitions` is an array
of `object`, then it must be an array of security
Requirement Objects, e.g. `[{apikey: []}]`.

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| definitions | <code>array</code> | An array of the Security Definition to apply. |

<a name="module_openapi-doc..Swagger+globalParameter"></a>

#### swagger.globalParameter(param) ⇒ <code>Swagger</code>
Adds a global parameter to the document which can be referred to using $ref later.

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| param | <code>object</code> | A valid Swagger parameter specification. |

**Example**  
```js
swagger.globalParameter({
	 in: 'path',
	 name: 'foo',
	 type: 'string',
	 description: 'My foo param'});
swagger.post('/foo')
	.operationId('CreateFoo')
	.parameter({ $ref: '#/parameters/foo' })
	.response(200, 'Success');
```
<a name="module_openapi-doc..Swagger+globalTag"></a>

#### swagger.globalTag(tag) ⇒ <code>Swagger</code>
Adds a global tag to the document.

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| tag | <code>object</code> | A Swagger tag object. |

**Example**  
```js
swagger.globalTag({
	 name: 'foo',
	 description: 'My foo tag'});
```
<a name="module_openapi-doc..Swagger+globalResponse"></a>

#### swagger.globalResponse(name, description, [type], [isArray], [headers]) ⇒ <code>Swagger</code>
Adds a global response to the document which can be referred to using $ref later.

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| name | <code>string</code> | The unique name of the response. |
| description | <code>string</code> | The description of the response. |
| [type] | <code>string</code> | Optional type (to be used in `$ref`). |
| [isArray] | <code>boolean</code> | Optional indicator that the repsonse is an array of `type`. |
| [headers] | <code>array</code> | Optional headers to include in the response. |

<a name="module_openapi-doc..Swagger+globalExternalDocs"></a>

#### swagger.globalExternalDocs(doc) ⇒ <code>Swagger</code>
Sets the global externalDocs of the swagger doc

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  

| Param | Type | Description |
| --- | --- | --- |
| doc | <code>string</code> | A valid ExternalDocumentationObject. |

<a name="module_openapi-doc..Swagger+globalConsumes"></a>

#### swagger.globalConsumes(mimeType) ⇒ <code>Swagger</code>
Adds a consumes to the doc

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this)  

| Param | Type | Description |
| --- | --- | --- |
| mimeType | <code>string</code> \| <code>Array.&lt;string&gt;</code> | MimeType or array of mimetypes to add |

<a name="module_openapi-doc..Swagger+globalProduces"></a>

#### swagger.globalProduces(mimeType) ⇒ <code>Swagger</code>
Adds a produces to the doc

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this)  

| Param | Type | Description |
| --- | --- | --- |
| mimeType | <code>string</code> \| <code>Array.&lt;string&gt;</code> | MimeType or array of mimetypes to add |

<a name="module_openapi-doc..Swagger+nosecurity"></a>

#### swagger.nosecurity() ⇒ <code>Swagger</code>
Sets no security on the current method.

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Example**  
```js
swagger.get('/foos/:id')
    .nosecurity();
```
<a name="module_openapi-doc..Swagger+schema"></a>

#### swagger.schema(name, spec) ⇒ <code>Swagger</code>
Adds a schema definition to the API.

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| name | <code>string</code> | The type name. |
| spec | <code>object</code> | A valid JSON schema draft 04 spec. |

**Example**  
```javascript
const spec = { type: 'object', properties: { name: { type: 'string' } } };
swagger.schema('Item', spec)
    .get('/items')
    .response(200, 'Success', 'Item', true);
swagger.schema('Item', spec)
    .get('/items/:id')
    .response(200, 'Success', 'Item');
```
<a name="module_openapi-doc..Swagger+schemas"></a>

#### swagger.schemas(schemas) ⇒ <code>Swagger</code>
Adds multiple schema to the API.

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  

| Param | Type | Description |
| --- | --- | --- |
| schemas | <code>array</code> | schemas to add |

<a name="module_openapi-doc..Swagger+post"></a>

#### swagger.post(path, [options]) ⇒ <code>Swagger</code>
Creates a post method for the specified path.  Use Express style routing.

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| path | <code>string</code> |  | The path for the method. |
| [options] | <code>object</code> |  | Options for controlling the merge. |
| [options.express] | <code>boolean</code> | <code>true</code> | All expressjs paths will be rewritten to Swagger. |

**Example**  
```js
swagger.post('/foos');
```
<a name="module_openapi-doc..Swagger+get"></a>

#### swagger.get(path, [options]) ⇒ <code>Swagger</code>
Creates a get method for the specified path.  Use Express style routing.

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| path | <code>string</code> |  | The path for the method. |
| [options] | <code>object</code> |  | Options for controlling the merge. |
| [options.express] | <code>boolean</code> | <code>true</code> | All expressjs paths will be rewritten to Swagger. |

**Example**  
```js
swagger.get('/foos/:id');
```
<a name="module_openapi-doc..Swagger+put"></a>

#### swagger.put(path, [options]) ⇒ <code>Swagger</code>
Creates a put method for the specified path.  Use Express style routing.

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| path | <code>string</code> |  | The path for the method. |
| [options] | <code>object</code> |  | Options for controlling the merge. |
| [options.express] | <code>boolean</code> | <code>true</code> | All expressjs paths will be rewritten to Swagger. |

**Example**  
```js
swagger.put('/foos/:id');
```
<a name="module_openapi-doc..Swagger+delete"></a>

#### swagger.delete(path, [options]) ⇒ <code>Swagger</code>
Creates a delete method for the specified path.  Use Express style routing.

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| path | <code>string</code> |  | The path for the method. |
| [options] | <code>object</code> |  | Options for controlling the merge. |
| [options.express] | <code>boolean</code> | <code>true</code> | All expressjs paths will be rewritten to Swagger. |

**Example**  
```js
swagger.delete('/foos/:id');
```
<a name="module_openapi-doc..Swagger+patch"></a>

#### swagger.patch(path, [options]) ⇒ <code>Swagger</code>
Creates a patch method for the specified path.  Use Express style routing.

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| path | <code>string</code> |  | The path for the method. |
| [options] | <code>object</code> |  | Options for controlling the merge. |
| [options.express] | <code>boolean</code> | <code>true</code> | All expressjs paths will be rewritten to Swagger. |

**Example**  
```js
swagger.patch('/foos/:id');
```
<a name="module_openapi-doc..Swagger+head"></a>

#### swagger.head(path, [options]) ⇒ <code>Swagger</code>
Creates a head method for the specified path.  Use Express style routing.

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| path | <code>string</code> |  | The path for the method. |
| [options] | <code>object</code> |  | Options for controlling the merge. |
| [options.express] | <code>boolean</code> | <code>true</code> | All expressjs paths will be rewritten to Swagger. |

**Example**  
```js
swagger.head('/foos/:id');
```
<a name="module_openapi-doc..Swagger+options"></a>

#### swagger.options(path, [options]) ⇒ <code>Swagger</code>
Creates a options method for the specified path.  Use Express style routing.

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| path | <code>string</code> |  | The path for the method. |
| [options] | <code>object</code> |  | Options for controlling the merge. |
| [options.express] | <code>boolean</code> | <code>true</code> | All expressjs paths will be rewritten to Swagger. |

**Example**  
```js
swagger.options('/foos/:id');
```
<a name="module_openapi-doc..Swagger+summary"></a>

#### swagger.summary(summary) ⇒ <code>Swagger</code>
Sets the summary for the current method.

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| summary | <code>string</code> | The summary for the method. |

**Example**  
```js
swagger.delete('/foos/:id').summary('Deletes foo.');
```
<a name="module_openapi-doc..Swagger+description"></a>

#### swagger.description(description) ⇒ <code>Swagger</code>
Sets the description for the current method.

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| description | <code>string</code> | The description for the method. |

**Example**  
```js
swagger.delete('/foos/:id').description('Deletes foo');
```
<a name="module_openapi-doc..Swagger+operationId"></a>

#### swagger.operationId(name) ⇒ <code>Swagger</code>
Sets the operationId for the current method.

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| name | <code>string</code> | The name for the method. |

**Example**  
```js
swagger.delete('/foos/:id').operationId('DeleteFoo');
```
<a name="module_openapi-doc..Swagger+tag"></a>

#### swagger.tag(tag) ⇒ <code>Swagger</code>
Adds a tag to the current method.

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| tag | <code>string</code> | The tag to add. |

**Example**  
```js
swagger.delete('/foos/:id').tag('foo');
```
<a name="module_openapi-doc..Swagger+tags"></a>

#### swagger.tags(tags) ⇒ <code>Swagger</code>
Adds multiple tags to the current method.

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| tags | <code>Array.&lt;string&gt;</code> | The tags for the method. |

**Example**  
```js
swagger.delete('/foos/:id').tags(['foo', 'bar']);
```
<a name="module_openapi-doc..Swagger+body"></a>

#### swagger.body(type, description) ⇒ <code>Swagger</code>
Convenience method to add a body parameter to the current method.

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| type | <code>string</code> | The type of object (not full ref), e.g. "Type" |
| description | <code>string</code> | The description of the body parameter. |

**Example**  
```js
swagger.post('/foo').body('Foo', 'Foo to create');
```
<a name="module_openapi-doc..Swagger+parameter"></a>

#### swagger.parameter(param) ⇒ <code>Swagger</code>
Adds a parameter to the current method.

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| param | <code>object</code> | A valid Swagger parameter specification. |

**Example**  
```js
swagger.post('/foo').parameter({
	 in: 'path',
	 name: 'foo',
	 type: 'string',
	 description: 'My foo param'});
```
<a name="module_openapi-doc..Swagger+parameters"></a>

#### swagger.parameters(parameters) ⇒ <code>Swagger</code>
Sets multiple parameters on the current method.

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| parameters | <code>array</code> | A valid Swagger parameters array. |

<a name="module_openapi-doc..Swagger+extension"></a>

#### swagger.extension(key, value) ⇒ <code>Swagger</code>
Adds an extension to either the current method or the doc.

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| key | <code>string</code> | The x- extension to add |
| value | <code>object</code> \| <code>array</code> \| <code>number</code> \| <code>null</code> \| <code>string</code> \| <code>boolean</code> | the value of the extension |

<a name="module_openapi-doc..Swagger+consumes"></a>

#### swagger.consumes(mimeType) ⇒ <code>Swagger</code>
Adds a consumes to the current method.

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| mimeType | <code>string</code> \| <code>Array.&lt;string&gt;</code> | The mime-type that can be consumed. |

<a name="module_openapi-doc..Swagger+produces"></a>

#### swagger.produces(mimeType, forceGlobal) ⇒ <code>Swagger</code>
Adds a produces to the current method.

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| mimeType | <code>string</code> \| <code>Array.&lt;string&gt;</code> | The mime-type that can be consumed. |
| forceGlobal | <code>boolean</code> | Write to the document level produces even if in a path. |

<a name="module_openapi-doc..Swagger+response"></a>

#### swagger.response(code, [description], [type], [isArray], [headers], [noValidation]) ⇒ <code>Swagger</code>
Adds a response to the current method.

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| code | <code>number</code> | The HTTP response code. |
| [description] | <code>string</code> | Optional description. 		If not specified, uses the standard HTTP response string. |
| [type] | <code>string</code> | Optional type (to be used in `$ref`). |
| [isArray] | <code>boolean</code> | Optional indicator that the repsonse is an array of `type`. |
| [headers] | <code>array</code> | Optional headers to include in the response. |
| [noValidation] | <code>boolean</code> | remove extra validation steps. |

<a name="module_openapi-doc..Swagger+responses"></a>

#### swagger.responses(responses, [options]) ⇒ <code>Swagger</code>
Sets multiple response on the current method.

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| responses | <code>object</code> | A valid Swagger responses object. |
| [options] | <code>object</code> | Options for controlling the merge. |
| [options.extensions] | <code>RegExp</code> | Test to allow (or deny) extensions. |
| [options.noValidation] | <code>booelan</code> | disable extra validation checks. |

<a name="module_openapi-doc..Swagger+action"></a>

#### swagger.action(handler) ⇒ <code>Swagger</code>
Applies an action to the current method to be used with Express.

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| handler | <code>expressHandlerCallback</code> | The Express handler function. |

<a name="module_openapi-doc..Swagger+merge"></a>

#### swagger.merge(swagger, [options]) ⇒ <code>Swagger</code>
Merges a well defined swagger document into this one by merging
all definitions, paths, responses, tags, and externalDocs into this document.

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| swagger | <code>object</code> |  | A well defined swagger document. |
| [options] | <code>object</code> |  | Options for controlling the merge. |
| [options.prefix] | <code>string</code> |  | All paths will be prefixed with `prefix`. |
| [options.express] | <code>boolean</code> | <code>true</code> | All expressjs paths will be rewritten to Swagger. |
| [options.filter] | <code>pathFilter</code> |  | Selectively filter paths. |
| [options.mergeBlacklist] | <code>Array.&lt;string&gt;</code> | <code>[]</code> | Skip over these properties when merging |

<a name="module_openapi-doc..Swagger+_sanitizeProperties"></a>

#### swagger.\_sanitizeProperties(props) ⇒ <code>Swagger</code>
Sanitizes the current document with respect to a list of `props`.  It will delete any
matching global properties and any method level properties that match.

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this)  

| Param | Type | Description |
| --- | --- | --- |
| props | <code>Array.&lt;string&gt;</code> | A list of properties to delete. |

<a name="module_openapi-doc..Swagger+externalDocs"></a>

#### swagger.externalDocs(doc) ⇒ <code>Swagger</code>
Sets externalDocs on the current method.

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  

| Param | Type | Description |
| --- | --- | --- |
| doc | <code>string</code> | A valid ExternalDocumentationObject. |

<a name="module_openapi-doc..Swagger+paths"></a>

#### swagger.paths(swagger, [options]) ⇒ <code>Swagger</code>
Merges a well defined swagger paths into this one by merging the paths found
in the supplied `swagger.paths` into this document.

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>Swagger</code> - The current object (this).  
**Access**: public  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| swagger | <code>object</code> |  | A well defined swagger document. |
| [options] | <code>object</code> |  | Options for controlling the merge. |
| [options.defaultResponses] | <code>object</code> |  | Applies a default set of responses  to all methods when merging, but will not override existing responses. |
| [options.responses] | <code>object</code> |  | Applies all responses to all methods when merging, overriding any existing responses. |
| [options.prefix] | <code>string</code> |  | All paths will be prefixed with `prefix`. |
| [options.express] | <code>boolean</code> | <code>true</code> | All expressjs paths will be rewritten to Swagger. |
| [options.filter] | <code>pathFilter</code> |  | Selectively filter paths. |
| [options.noValidation] | <code>boolean</code> |  | disable extra validation |
| [options.extensions] | <code>RegExp</code> |  | Test to allow (or deny) extensions from 											paths and responses. |

<a name="module_openapi-doc..Swagger+apidoc"></a>

#### swagger.apidoc() ⇒ <code>object</code>
Returns the Swagger 2.0 API document.

**Kind**: instance method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>object</code> - Swagger 2.0 API document.  
**Access**: public  
<a name="module_openapi-doc..Swagger.forEachAction"></a>

#### Swagger.forEachAction(swagger, callback)
Iterates over each endpoint in the swagger document.  Useful for binding
to Express.

**Kind**: static method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| swagger | <code>Swagger</code> | The swagger document. |
| callback | <code>forEachActionCallback</code> | Called for each endpoint action. |

<a name="module_openapi-doc..Swagger.actionMiddleware"></a>

#### Swagger.actionMiddleware(swagger, verb, path) ⇒ <code>object</code>
Gets the Swagger action middleware function for Express.

**Kind**: static method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>object</code> - The middleware for the specified endpoint  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| swagger | <code>Swagger</code> | The swagger document. |
| verb | <code>string</code> | The HTTP verb. |
| path | <code>string</code> | The HTTP path. |

<a name="module_openapi-doc..Swagger.securityMiddleware"></a>

#### Swagger.securityMiddleware(swagger, verb, path) ⇒ <code>function</code>
Gets the Swagger security middleware function for Express.

**Kind**: static method of [<code>Swagger</code>](#module_openapi-doc..Swagger)  
**Returns**: <code>function</code> - middleware  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| swagger | <code>Swagger</code> | The swagger document. |
| verb | <code>string</code> | The HTTP verb. |
| path | <code>string</code> | The HTTP path. |

<a name="module_openapi-doc..customAuthentication"></a>

### openapi-doc~customAuthentication ⇒ <code>boolean</code>
Callback function for custom authentication.

**Kind**: inner typedef of [<code>openapi-doc</code>](#module_openapi-doc)  
**Returns**: <code>boolean</code> - Return `true` if valid, or `false` if invalid.  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| req | <code>object</code> | The express request object. |

<a name="module_openapi-doc..expressHandlerCallback"></a>

### openapi-doc~expressHandlerCallback : <code>function</code>
Callback for handling Express action.

**Kind**: inner typedef of [<code>openapi-doc</code>](#module_openapi-doc)  

| Param | Type | Description |
| --- | --- | --- |
| request | <code>object</code> | The Express request object. |
| response | <code>object</code> | The Express response object. |

<a name="module_openapi-doc..pathFilter"></a>

### openapi-doc~pathFilter ⇒ <code>boolean</code>
Callback function to selectively filter out specific methods.  Return true
to include the path.

**Kind**: inner typedef of [<code>openapi-doc</code>](#module_openapi-doc)  
**Returns**: <code>boolean</code> - Return `true` if include, or `false` to exclude.  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| swagger | <code>object</code> | The swagger document. |
| path | <code>string</code> | The path. |
| verb | <code>string</code> | The verb. |

<a name="module_openapi-doc..forEachActionCallback"></a>

### openapi-doc~forEachActionCallback : <code>function</code>
Callback for iterating over Swagger endpoint actions.

**Kind**: inner typedef of [<code>openapi-doc</code>](#module_openapi-doc)  

| Param | Type | Description |
| --- | --- | --- |
| path | <code>string</code> | The endpoint path. |
| verb | <code>string</code> | The endpoint verb. |


## Author

Axway <support@axway.com> https://axway.com

## License

This code is proprietary, closed source software licensed to you by Axway. All Rights Reserved. You may not modify Axway’s code without express written permission of Axway. You are licensed to use and distribute your services developed with the use of this software and dependencies, including distributing reasonable and appropriate portions of the Axway code and dependencies. Except as set forth above, this code MUST not be copied or otherwise redistributed without express written permission of Axway. This module is licensed as part of the Axway Platform and governed under the terms of the Axway license agreement (General Conditions) located here: [https://support.axway.com/en/auth/general-conditions](https://support.axway.com/en/auth/general-conditions); EXCEPT THAT IF YOU RECEIVED A FREE SUBSCRIPTION, LICENSE, OR SUPPORT SUBSCRIPTION FOR THIS CODE, NOTWITHSTANDING THE LANGUAGE OF THE GENERAL CONDITIONS, AXWAY HEREBY DISCLAIMS ALL SUPPORT AND MAINTENANCE OBLIGATIONS, AS WELL AS ALL EXPRESS AND IMPLIED WARRANTIES, INCLUDING BUT NOT LIMITED TO IMPLIED INFRINGEMENT WARRANTIES, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, AND YOU ACCEPT THE PRODUCT AS-IS AND WITH ALL FAULTS, SOLELY AT YOUR OWN RISK. Your right to use this software is strictly limited to the term (if any) of the license or subscription originally granted to you.