Fast, unopinionated, minimalist web framework for node.
This is a Node.js module available through the npm registry.
Before installing, download and install Node.js.
Installation is done using the
npm install
command:
$ npm install express-swagger-delta
OU
$ yarn add express-swagger-delta
To start using the library, it is necessary to create a base configuration file, following the structure:
Note: Follows the same structure pattern as the swagger.js documentation (openapi: 3.0.0).
import { description, name, version } from '../../package.json';
export const layout = {
explorer: false,
customSiteTitle: 'Example Documentation',
customCss: '.swagger-ui .topbar { display: none }',
swaggerOptions: {
docExpansion: 'none',
},
};
export const specification = {
info: {
name: name,
version: version,
description: description,
title: 'Example Documentation',
},
servers: [
{
url: `http://localhost:8080/api`,
},
],
components: {
securitySchemes: {
ExampleKey: {
in: 'header',
type: 'apiKey',
name: 'ExampleKey',
},
},
schemas: {
Return: {
type: 'object',
properties: {
statusCode: {
type: 'integer',
format: 'int64',
description: 'Request Status Code',
},
message: {
type: 'string',
description: 'Request Status Message',
},
content: {
type: 'object',
description: 'Request Content',
},
},
},
},
responses: {
default: {
description: 'Api Default Return',
content: {
'application/json': {
schema: {
$ref: '#/components/schemas/Return',
},
},
},
},
},
},
};
That done, you need to configure the server, which can be done as follows:
import { json, urlencoded } from 'body-parser';
import cors from 'cors';
import helmet from 'helmet';
import ExpressSwagger from '../../dist/index';
import ExampleController from '../controllers/ExampleController';
import AuthService from '../services/AuthService';
import { layout, specification } from './swagger';
class Server {
constructor() {
this.server = ExpressSwagger.Server;
this.server.NODE_ENV = 'test';
this.server.BASE_HOST = 'localhost';
this.server.BASE_PATH = '/api';
this.server.PORT = 8080;
this.server.setSwaggerProps({
layout: layout,
specification: specification,
});
this.server.app.use(cors());
this.server.app.use(helmet());
this.server.app.use(urlencoded({ extended: true }));
this.server.app.use(json({ limit: '2gb' }));
this.server.middleware = this.middleware;
this.server.authMiddleware = this.authMiddleware;
ExampleController.setRoutes();
this.server.initialize();
}
authMiddleware(req, res, next) {
AuthService.checkAuth(req)
.then((auth) => {
switch (auth.statusCode) {
case 200:
return next();
case 400:
return res.status(400).json(auth);
case 401:
return res.status(401).json(auth);
}
})
.catch((err) => res.status(500).json(err));
}
middleware(req, res, callback) {
callback(req, res)
.then((data) => res.status(data.statusCode).json(data))
.catch((err) => res.status(500).json(err));
}
listen = (port) => this.server.listen(port);
}
export default new Server();
To add a route to the server it is necessary to create a file for building routes by calling an option from the ExpressSwagger property and thus passing its parameters, that way the API documentation and route will already be created, see:
Note: The parameter object follows the same structure pattern as swagger.js documentation (openapi: 3.0.0).
import ExpressSwagger from '../../dist/index';
import { specification } from '../configs/swagger';
import Return from '../models/Return';
export default class ExampleController {
static setRoutes() {
ExpressSwagger.Server.addRoute({
auth: true,
method: 'GET',
path: '/example',
tags: ['Example'],
summary: 'Example Controller',
security: [specification.components.securitySchemes],
responses: specification.components.responses,
handler: async (req) => {
return new Return(200, 'OK', {
date: new Date(),
});
},
});
ExpressSwagger.Server.addRoute({
auth: true,
method: 'GET',
path: '/example/:text',
tags: ['Example'],
summary: 'Example Controller',
security: [specification.components.securitySchemes],
responses: specification.components.responses,
parameters: [
{
in: 'path',
required: true,
name: 'text',
schema: {
type: 'string',
},
description: 'Text to print in the response',
},
],
handler: async (req) => {
return new Return(200, 'OK', {
date: new Date(),
text: req.params.text,
});
},
});
}
}
🥇 Donato C. Ávila |
Thiago S. Oliveira |