<commit_before># swagger-spec-express

> Programmatically generate your Swagger specification (JSON) file.

![NPM](https://nodei.co/npm/swagger-spec-express.png)

![Build status](https://travis-ci.org/eXigentCoder/swagger-spec-express.svg?branch=master)

A library that allows you to programmatically annotate your existing express api with [swagger](http://swagger.io/) info and then generate and validate your json spec file. All without completely starting over or changing the structure of your express routes.

## Why

There are already a few libraries out there to add Swagger documentation to your [express](https://expressjs.com/) api, like [swagger-node-express](https://www.npmjs.com/package/swagger-node-express) and [swagger-node](https://github.com/swagger-api/swagger-node) which work really well, however they require you to either start from scratch or change your routes to work with their format. This libary is different and can easily be added to an existing and established express api using the normal patterns you are used to.

##Installation
**Requires Express 4.x**

Install the package:

> npm install swagger-spec-express --save-exact

Basic code example:

```javascript
var express = require('express');
var swagger = require('swagger-spec-express');
var packageJson = require('./package.json');

var app = express();
var options = {
    title: packageJson.title,
    version: packageJson.version
};
swagger.initialise(app, options);

app.get('/swagger.json', function (err, res) {
    res.status(200).json(swagger.json());
}).describe({
    responses: {
        200: {
            description: "Returns the swagger.json document"
        }
    }
});

swagger.compile();
var port = 3000;
app.listen(port, appListening);
function appListening() {
    console.info(packageJson.name + ' is listening on port ' + port);
}
```

This will create a very basic express app that serves up the swagger.json document when you navigate to **<http://localhost:3000/swagger.json>**

The [JSON Schema](http://json-schema.org/) file that will be used to validate the supplied
metadata on the route can be found [here](https://raw.githubusercontent.com/eXigentCoder/swagger-spec-express/master/lib/schemas/meta-data.json) in addition the fields are detailed below. Wherever possible the library tries to adhear to the official [Swagger Specification](http://swagger.io/specification/) so that is a good place to look for extra information about what you can specify.

## Describing Your Routes

As seen above, once you have called initialise on your app, the describe method is automatically added and can be added to routes you declare directly on your app object.

But what if you want to use the router object? In the above example code above add the following to the top of the page:

```javascript
var exampleRouter = require('./example-route');
```

And then after calling **swagger.initialise(app, options);** add the following:

```javascript
app.use(exampleRouter);
```

Code for the example router:

```javascript
'use strict';
var express = require('express');
var swagger = require('swagger-spec-express');
var router = new express.Router();
swagger.swaggerize(router);
module.exports = router;

router.get('/one', function (req, res) {
    res.status(200).json({example: 1})
}).describe({
    responses: {
        200: {
            description: "Returns example 1"
        }
    }
});
```

## Adding the UI

Simply follow the [instructions for the official Swagger UI project.](https://github.com/swagger-api/swagger-ui) or use your favourite, alternative Swagger UI theme.

## API

<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

### Table of Contents

-   Core:
-   [Initialise](#initialise)
-   [Swaggerise](#swaggerise)
-   [Describe](#describe)
-   [Compile](#compile)
-   [Validate](#validate)
-   [Json](#json)
-   Adding common items:
-   [Add Tag](#addTag)
-   [Add Header Parameter](#addHeaderParameter)
-   [Add Body Parameter](#addBodyParameter)
-   [Add Query Parameter](#addQueryParameter)
-   [Add Form Data Parameter](#addFormDataParameter)
-   [Add Path Parameter](#addPathParameter)
-   [Add Response](#addResponse)
-   [Add Response Header](#addResponseHeader)
-   [Add Model](#addModel)<commit_msg>fixing links.<commit_after># swagger-spec-express

> Programmatically generate your Swagger specification (JSON) file.

![NPM](https://nodei.co/npm/swagger-spec-express.png)

![Build status](https://travis-ci.org/eXigentCoder/swagger-spec-express.svg?branch=master)

A library that allows you to programmatically annotate your existing express api with [swagger](http://swagger.io/) info and then generate and validate your json spec file. All without completely starting over or changing the structure of your express routes.

## Why

There are already a few libraries out there to add Swagger documentation to your [express](https://expressjs.com/) api, like [swagger-node-express](https://www.npmjs.com/package/swagger-node-express) and [swagger-node](https://github.com/swagger-api/swagger-node) which work really well, however they require you to either start from scratch or change your routes to work with their format. This libary is different and can easily be added to an existing and established express api using the normal patterns you are used to.

##Installation
**Requires Express 4.x**

Install the package:

> npm install swagger-spec-express --save-exact

Basic code example:

```javascript
var express = require('express');
var swagger = require('swagger-spec-express');
var packageJson = require('./package.json');

var app = express();
var options = {
    title: packageJson.title,
    version: packageJson.version
};
swagger.initialise(app, options);

app.get('/swagger.json', function (err, res) {
    res.status(200).json(swagger.json());
}).describe({
    responses: {
        200: {
            description: "Returns the swagger.json document"
        }
    }
});

swagger.compile();
var port = 3000;
app.listen(port, appListening);
function appListening() {
    console.info(packageJson.name + ' is listening on port ' + port);
}
```

This will create a very basic express app that serves up the swagger.json document when you navigate to **<http://localhost:3000/swagger.json>**

The [JSON Schema](http://json-schema.org/) file that will be used to validate the supplied
metadata on the route can be found [here](https://raw.githubusercontent.com/eXigentCoder/swagger-spec-express/master/lib/schemas/meta-data.json) in addition the fields are detailed below. Wherever possible the library tries to adhear to the official [Swagger Specification](http://swagger.io/specification/) so that is a good place to look for extra information about what you can specify.

## Describing Your Routes

As seen above, once you have called initialise on your app, the describe method is automatically added and can be added to routes you declare directly on your app object.

But what if you want to use the router object? In the above example code above add the following to the top of the page:

```javascript
var exampleRouter = require('./example-route');
```

And then after calling **swagger.initialise(app, options);** add the following:

```javascript
app.use(exampleRouter);
```

Code for the example router:

```javascript
'use strict';
var express = require('express');
var swagger = require('swagger-spec-express');
var router = new express.Router();
swagger.swaggerize(router);
module.exports = router;

router.get('/one', function (req, res) {
    res.status(200).json({example: 1})
}).describe({
    responses: {
        200: {
            description: "Returns example 1"
        }
    }
});
```

## Adding the UI

Simply follow the [instructions for the official Swagger UI project.](https://github.com/swagger-api/swagger-ui) or use your favourite, alternative Swagger UI theme.

## API

<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

### Table of Contents

-   Core:
-   [Initialise](#initialise)
-   [Swaggerise](#swaggerise)
-   [Describe](#describe)
-   [Compile](#compile)
-   [Validate](#validate)
-   [Json](#json)
-   Adding common items:
-   [Add Tag](#addtag)
-   [Add Header Parameter](#addheaderparameter)
-   [Add Body Parameter](#addbodyparameter)
-   [Add Query Parameter](#addqueryparameter)
-   [Add Form Data Parameter](#addformdataparameter)
-   [Add Path Parameter](#addpathparameter)
-   [Add Response](#addresponse)
-   [Add Response Header](#addresponseheader)
-   [Add Model](#addmodel)
{'fraction_non_alphanumeric': 0.1199021207177814, 'fraction_numerical': 0.005360055931018411, 'mean_word_length': 4.334369173399627, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 11, 'https://': 14, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5463376', 'n_tokens_mistral': 2487, 'n_tokens_neox': 2373, 'n_words': 860}