Swagger with Existing Node app for API definition
tkssharma/Training-App-Node-Api Training-App-Node-Api — Node js API for my own applicationgithub.com
Swagger
Swagger is a specification for describing, producing, consuming, testing, and visualizing a RESTful API. It provides a number of tools for automatically generating documentation based on a given endpoint.
Now when you make changes to your code, your documentation is updated and synchronized with the API so that consumers can quickly learn which resources are available, how to access them, and what to expect (status code, content-type, etc.) when interacting with the various endpoints.
Getting Started
Starting a New Project
If you’re starting a new project, you can easily generate the Swagger Specification and project boilerplate using the Swagger Editor. Test it out here.
If you don’t like the generated project structure, you can just export the JSON (or YAML) spec file and then use a custom generator, like Swaggerize Express, to generate the boilerplate. Then when you need to make changes to the API, you can just update the spec file. Simple.
Generating the Swagger Spec
To generate the Swagger specification, we will be using swagger-jsdoc.
Install swagger-jsdoc:
$ npm install swagger-jsdoc@1.3.0 --save
Add the requirement to app.js:
var swaggerJSDoc = require('swagger-jsdoc');
Then add the following code to app.js just below var app = express();
// swagger definition
var swaggerDefinition = {
info: {
title: 'Node Swagger API',
version: '1.0.0',
description: 'Demonstrating how to describe a RESTful API with Swagger',
},
host: 'localhost:3000',
basePath: '/',
};
// options for the swagger docs
var options = {
// import swaggerDefinitions
swaggerDefinition: swaggerDefinition,
// path to the API docs
apis: ['.//routes/*.js','routes.js'],// pass all in array
};
// initialize swagger-jsdoc
var swaggerSpec = swaggerJSDoc(options);Take note of the comments above. This code essentially initializes swagger-jsdoc and adds the appropriate metadata to the Swagger specification.
Add the route to serve up the Swagger spec:
*// serve swagger* app.get('/swagger.json', function(req, res) { res.setHeader('Content-Type', 'application/json'); res.send(swaggerSpec); });Fire up the server and navigate to http://localhost:3000/swagger.json to see the basic spec:
{
info: {
title: "Node Swagger API",
version: "1.0.0",
description: "Demonstrating how to describe a RESTful API with Swagger"
},
host: "localhost:3000",
basePath: "/",
swagger: "2.0",
paths: { },
definitions: { },
responses: { },
parameters: { },
securityDefinitions: { }
}Now we need to update the routes…
Updating the Route Handlers
swagger-jsdoc uses JSDoc-style comments to generate the Swagger spec. So, add such comments, in YAML, to the route handlers that describe their functionality.
HTTP GET
/
* [@swagger](http://twitter.com/swagger)
* /api/users:
* get:
* tags:
* - users
* description: Returns all users
* produces:
* - application/json
* responses:
* 200:
* description: An array of users
* schema:
* $ref: '#/definitions/users'
*/Add the comments in /routes/index.js just above the handler, like so:
This should be fairly self-explanatory. We have an /api/users endpoint that returns a 200 response to a GET request. The $ref is used to re-use definitions to keep the code DRY.
Add the following code above the previous code to get $ref
/
* [@swagger](http://twitter.com/swagger)
* definition:
* users:
* properties:
* name:
* type: string
* email:
* type: string
* age:
* type: integer
* sex:
* type: string
*/Now we can use that definition for each of the HTTP methods.
For more information and examples, please see the Swagger Specification.
HTTP POST
/
* [@swagger](http://twitter.com/swagger)
* /api/users:
* post:
* tags:
* - users
* description: Creates a new user
* produces:
* - application/json
* parameters:
* - name: tarun
* description: user object
* in: body
* required: true
* schema:
* $ref: '#/definitions/user'
* responses:
* 200:
* description: Successfully created
*/HTTP PUT
/
* [@swagger](http://twitter.com/swagger)
* /api/users/{id}:
* put:
* tags: users
* description: Updates a single user
* produces: application/json
* parameters:
* name: tarun
* in: body
* description: Fields for the user resource
* schema:
* type: array
* $ref: '#/definitions/user'
* responses:
* 200:
* description: Successfully updated
*/HTTP DELETE
/
* [@swagger](http://twitter.com/swagger)
* /api/users/{id}:
* delete:
* tags:
* - users
* description: Deletes a single user
* produces:
* - application/json
* parameters:
* - name: id
* description: user's id
* in: path
* required: true
* type: integer
* responses:
* 200:
* description: Successfully deleted
*/Check out the updated spec at http://localhost:3000/swagger.json.
Adding Swagger UI
Finally, download the Swagger UI repo, add the “dist” folder from the downloaded repo to the “public” folder in the project directory, and then rename the directory to “api-docs”.
Now within index.html inside the “api-docs” directory just update this line-
url = "http://petstore.swagger.io/v2/swagger.json";
To
url = "http://localhost:3000/swagger.json";
Finally, navigate to http://localhost:3000/api-docs/ in your browser to test out the API endpoints:
final my server look like this and app is running on port 3000
import swagger from 'app/swagger';
let app = express();
app.use(express.static(path.join(__dirname, 'public')));
//---------------------------------------------//
// invoke routes, MIddleware, Mongo connect here
new MongoConnect();
new AppMiddleware(app);
new AppRoutes(app, express);
new swagger(app);
//---------------------------------------------//
let server = app.listen(
app.get('port'),
() => {
const port = process.env.port || server.address().port;
winston.log('info', `GenNext API running at [http://localhost:${port}`](http://localhost:${port}`))
console.log('runing...')
}
);
export default app;Let me know if any issues while doing app setup.
Keep learning ….
Comments