cti-swagger
v1.2.0
Published
A documentation generator for CTI
Downloads
8
Readme
cti-swagger
Generate API documentation with Swagger and annotated source files.
Sections:
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
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
- Clone this repo:
git clone https://github.com/CanTireInnovations/cti-swagger.git
- Navigate to repo contents
cd cti-swagger
- Install script dependencies
npm install
- Choose which way to launch the UI
- Launch Locally Automatically
- Build and launch Swagger-UI with docker
npm run docker
- Build and launch Swagger-UI with docker
- Launch Manually
1. 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
2. Launch withdocker run -p 127.0.0.1:8080:8080 cantireinnovations/swagger-ui:VERSION
- This should build the image
- 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.