cti-swagger

Generate API documentation with Swagger and annotated source files.

Sections:

• Usage as an NPM Build Script
• How to Document the API
• How to Launch Swagger UI with Docker

Usage as an NPM Build Script

Run npm install cti-swagger --save-dev

package.json

...
    "scripts" : {
        "docs": "cti-swagger source-folder/ output-folder/swagger.json"
    }
...

Example Swagger Annotated Controller

controllers/login-controller.js

/**
 * @swagger
 * /login:
 *   post:
 *     description: Login to the application
 *     produces:
 *       - application/json
 *     parameters:
 *       - name: username
 *         description: Username to use for login.
 *         in: formData
 *         required: true
 *         type: string
 *       - name: password
 *         description: User's password.
 *         in: formData
 *         required: true
 *         type: string
 *     responses:
 *       200:
 *         description: login
 */
app.post( '/login', function( req, res ) {
    res.json( req.body );
} );

Global Definitions

• HALLink

Example Usage

/**
 * @swagger
 * definition:
 *   myHALObject:
 *     type: object
 *     properties:
 *       value : { type: string }
 *       _links:
 *          type: object
 *          properties:
 *            self: { $ref: '#/definitions/HALLink' }
 */

Advanced Options

CTI_SWAGGER_EXCLUDE

Default Value : ^node_modules$

Description:

Specify the environment variable CTI_SWAGGER_EXCLUDE to specify which folders/filenames should not be scanned for swagger annotated .js files

How to Launch Swagger UI with Docker

1. Clone this repo: git clone https://github.com/CanTireInnovations/cti-swagger.git

2. Navigate to repo contents cd cti-swagger

3. Install script dependencies npm install

4. Choose which way to launch the UI

5. Launch Locally Automatically

   1. Build and launch Swagger-UI with docker npm run docker

6. Launch Manually

7. Build the docker image npm run docker.build

   • This should build the image cantireinnovations/swagger-ui:VERSION where version is extracted from ./swagger-ui/package.json

8. Launch with docker run -p 127.0.0.1:8080:8080 cantireinnovations/swagger-ui:VERSION

9. Your swagger.json can now be loaded in the UI via query string parameter url or by pasting the url string into the text field and clicking Explore.