Swagger UI for Pip.Services in Dart #

此模块是 Pip.Services 多语言微服务工具包的一部分。

Swagger 模块提供了一个可以添加到微服务中的 Swagger UI，并且可以无缝地与现有的 REST 和可命令的 HTTP 服务集成。

该模块包含以下包：

• Build - Swagger 服务工厂
• Services - Swagger UI 服务

使用 #

在你的 pubspec.yaml 文件中添加以下依赖：

dependencies:
  pip_services3_swagger: version

然后从命令行安装包：

flutter pub get

开发一个 RESTful 服务组件。例如，它可能如下所示。在 register 方法中，我们加载了服务的 Open API 规范。 你也可以在构造函数中通过设置 _swaggerEnable 属性来默认启用 Swagger。

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');
  }
}

Open API 规范文件应如下所示准备，可以手动准备或使用 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'

在 config.yml 文件中包含 Swagger 服务并为你的 REST 或可命令的 HTTP 服务启用 Swagger。显式添加 HttpEndpoint 允许在 REST 服务和 Swagger 服务之间共享同一个端口。

---
...
# 共享 HTTP 端点
- descriptor: "pip-services:endpoint:http:default:1.0"
  connection:
    protocol: http
    host: localhost
    port: 8080

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

# 我的 RESTful 服务
- descriptor: "myservice:service:rest:default:1.0"
  swagger:
    enable: true

最后，记得将工厂添加到你的容器中，以便它可以创建所需的组件。

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

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

启动微服务并在浏览器中打开 Open API 规范页面： http://localhost:8080/greeting/swagger

然后使用链接 http://localhost:8080/swagger 打开 Swagger UI。结果应该类似于下图。

开发 #

为了开发，你需要安装以下前提条件：

• Dart SDK 2
• Visual Studio Code 或其他你喜欢的 IDE
• Docker

安装依赖：

flutter pub get

运行自动化测试：

flutter pub run test

生成 API 文档：

./docgen.ps1

在提交更改之前，运行 Docker 化构建和测试：

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

联系人 #

Dart 版本的 Pip.Services 由以下人员创建和维护：

• Sergey Seroukhov
• Danil Prisiazhnyi

文档由以下人员编写：

• Levichev Dmitry

example/main.dart

import 'dart:async';
import 'dart:io';

import 'package:pip_services3_commons/pip_services3_commons.dart';
import 'package:pip_services3_components/pip_services3_components.dart';
import 'package:pip_services3_rpc/pip_services3_rpc.dart';
import 'package:pip_services3_swagger/pip_services3_swagger.dart';

import 'logic/DummyController.dart';
import 'services/DummyCommandableHttpService.dart';
import 'services/DummyRestService.dart';

void main(List<String> args) async {
  // 创建组件
  var logger = ConsoleLogger();
  var controller = DummyController();
  var httpEndpoint = HttpEndpoint();
  var restService = DummyRestService();
  var httpService = DummyCommandableHttpService();
  var statusService = StatusRestService();
  var heartbeatService = HeartbeatRestService();
  var swaggerService = SwaggerService();

  var components = [
    controller,
    httpEndpoint,
    restService,
    httpService,
    statusService,
    heartbeatService,
    swaggerService
  ];

  // 配置组件
  logger.configure(ConfigParams.fromTuples(['level', 'trace']));

  httpEndpoint.configure(ConfigParams.fromTuples([
    'connection.protocol',
    'http',
    'connection.host',
    'localhost',
    'connection.port',
    8080
  ]));

  restService.configure(ConfigParams.fromTuples(['swagger.enable', true]));

  httpService.configure(ConfigParams.fromTuples(
      ['base_route', 'dummies2', 'swagger.enable', true]));

  try {
    // 设置引用
    var references = References.fromTuples([
      Descriptor('pip-services', 'logger', 'console', 'default', '1.0'),
      logger,
      Descriptor('pip-services', 'counters', 'log', 'default', '1.0'),
      LogCounters(),
      Descriptor('pip-services', 'endpoint', 'http', 'default', '1.0'),
      httpEndpoint,
      Descriptor(
          'pip-services-dummies', 'controller', 'default', 'default', '1.0'),
      controller,
      Descriptor('pip-services-dummies', 'service', 'rest', 'default', '1.0'),
      restService,
      Descriptor('pip-services-dummies', 'service', 'commandable-http',
          'default', '1.0'),
      httpService,
      Descriptor('pip-services', 'status-service', 'rest', 'default', '1.0'),
      statusService,
      Descriptor('pip-services', 'heartbeat-service', 'rest', 'default', '1.0'),
      heartbeatService,
      Descriptor('pip-services', 'swagger-service', 'http', 'default', '1.0'),
      swaggerService
    ]);

    Referencer.setReferences(references, components);

    // 打开组件
    await Opener.open(null, components);

    print('Press Ctrl-C to stop the microservice...');

    // 等待用户按下 ENTER 键
    var keyPresed = false;

    stdin.listen((List<int> event) {
      keyPresed = true;
    });

    while (!keyPresed) {
      await Future.delayed(Duration(milliseconds: 100));
    }

    await Closer.close(null, components);

    exit(0);
  } catch (ex) {
    logger.error(null, ex as Exception, 'Failed to execute the microservice');
    exit(1);
  }
}