pip_services3_swagger 1.0.1

Portable abstractions and patterns for Pip.Services in Dart

Swagger UI for Pip.Services in Dart

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:

• API Reference
• Change Log
• Get Help
• Contribute

Use

Add this to your package's pubspec.yaml file:

dependencies:
  pip_services3_swagger: version

Now you can install package from the command line:

pub get

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.

class MyRestService extends RestService {
  MyRestService() : super() {
    baseRoute = 'myservice';
    swaggerEnable = true;
  }

  FutureOr<Response> greeting(Request req) async {
    var name = req.params['name'];
    var response = 'Hello, ' + name.toString() + '!';
    return sendResult(req, response);
  }

  void register() {
    registerRoute(
        'get',
        '/greeting',
        ObjectSchema(true).withRequiredProperty('name', TypeCode.String),
        greeting);

    registerOpenApiSpecFromFile('./src/services/myservice.yml');
  }
}

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

openapi: '3.0.2'
info:
  title: 'MyService'
  description: 'MyService REST API'
  version: '1'
paths:
  /myservice/greeting:
    get:
      tags:
        - myservice
      operationId: 'greeting'
      parameters:
      - name: correlation_id
        in: query
        description: Correlation ID
        required: false
        schema:
          type: string
      - name: name
        in: query
        description: Name of a person
        required: true
        schema:
          type: string
      responses:
        200:
          description: 'Successful response'
          content:
            application/json:
              schema:
                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.

---
...
# Shared HTTP Endpoint
- descriptor: "pip-services:endpoint:http:default:1.0"
  connection:
    protocol: http
    host: localhost
    port: 8080

# Swagger Service
- descriptor: "pip-services:swagger-service:http:default:1.0"

# My RESTful Service
- descriptor: "myservice:service:rest:default:1.0"
  swagger:
    enable: true

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

...
import 'package:pip_services3_container/pip_services3_container.dart';
import 'package:pip_services3_swagger/pip_services3_swagger.dart';
import 'package:pip_services3_swagger/pip_services3_swagger.dart';

class MyProcess extends ProcessContainer {
  MyProcess(): super('myservice', 'MyService microservice') {
    
    factories.add(DefaultRpcFactory());
    factories.add(DefaultSwaggerFactory());
    factories.add(MyServiceFactory());
    ...
  }
}

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:

• Dart SDK 2
• Visual Studio Code or another IDE of your choice
• Docker

Install dependencies:

pub get

Run automated tests:

pub run test

Generate API documentation:

./docgen.ps1

Before committing changes run dockerized build and test as:

./build.ps1
./test.ps1
./clear.ps1

Contacts

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

• Sergey Seroukhov
• Danil Prisiazhnyi

The documentation is written by:

• Levichev Dmitry