Swagger UI for Pip.Services in Node.js / ES2017

This module is a part of the Pip.Services polyglot microservices toolkit.

The swagger module provides a Swagger UI that can be added into microservices and seamlessly integrated with existing REST and Commandable HTTP services.

The module contains the following packages:

• Build - Swagger service factory
• Services - Swagger UI service

Quick links:

• Change Log
• Get Help
• Contribute

Use

Install the NPM package as

1npm install pip-services3-swagger-nodex --save

Develop a RESTful service component. For example, it may look the following way. In the register method we load an Open API specification for the service. You can also enable swagger by default in the constractor by setting _swaggerEnable property.

1export class MyRestService extends RestService {
2    public constructor() {
3        super();
4        this._baseRoute = "myservice";
5        this._swaggerEnable = true;
6    }
7
8    private greeting(req, res) {
9        let name = req.params.name;
10        let response = "Hello, " + name + "!";
11        this.sendResult(req, res, response);
12    }
13        
14    public register() {
15        this.registerRoute(
16            'get', '/greeting', 
17            new ObjectSchema(true)
18                .withRequiredProperty("name", TypeCode.String),
19            this.greeting
20        );
21        
22        this.registerOpenApiSpecFromFile('./src/services/myservice.yml');
23    }
24}

The Open API specification for the service shall be prepared either manually or using Swagger Editor

1openapi: '3.0.2'
2info:
3  title: 'MyService'
4  description: 'MyService REST API'
5  version: '1'
6paths:
7  /myservice/greeting:
8    get:
9      tags:
10        - myservice
11      operationId: 'greeting'
12      parameters:
13      - name: correlation_id
14        in: query
15        description: Correlation ID
16        required: false
17        schema:
18          type: string
19      - name: name
20        in: query
21        description: Name of a person
22        required: true
23        schema:
24          type: string
25      responses:
26        200:
27          description: 'Successful response'
28          content:
29            application/json:
30              schema:
31                type: 'string'

Include Swagger service into config.yml file and enable swagger for your REST or Commandable HTTP services. Also explicitely adding HttpEndpoint allows to share the same port betwee REST services and the Swagger service.

1---
2...
3# Shared HTTP Endpoint
4- descriptor: "pip-services:endpoint:http:default:1.0"
5  connection:
6    protocol: http
7    host: localhost
8    port: 8080
9
10# Swagger Service
11- descriptor: "pip-services:swagger-service:http:default:1.0"
12
13# My RESTful Service
14- descriptor: "myservice:service:rest:default:1.0"
15  swagger:
16    enable: true

Finally, remember to add factories to your container, to allow it creating required components.

1...
2import { DefaultRpcFactory } from 'pip-services3-rpc-nodex';
3import { DefaultSwaggerFactory } from 'pip-services3-swagger-nodex';
4
5export class MyProcess extends ProcessContainer {
6  public constructor() {
7    super("myservice", "MyService microservice");
8    
9    this._factories.add(new DefaultRpcFactory());
10    this._factories.add(new DefaultSwaggerFactory());
11    this._factories.add(new MyServiceFactory());
12    ...
13  }
14}

Launch the microservice and open the browser to open the Open API specification at http://localhost:8080/greeting/swagger

Then open the Swagger UI using the link http://localhost:8080/swagger. The result shall look similar to the picture below.

Develop

For development you shall install the following prerequisites:

• Node.js 8+
• Visual Studio Code or another IDE of your choice
• Docker
• Typescript

Install dependencies:

1npm install

Compile the code:

1tsc

Run automated tests:

1npm test

Generate API documentation:

1./docgen.ps1

Before committing changes run dockerized build and test as:

1./build.ps1
2./test.ps1
3./clear.ps1

Contacts

The Node.js version of Pip.Services is created and maintained by:

• Sergey Seroukhov