Flutter Swagger集成插件pip_services4_swagger的使用

Flutter Swagger集成插件pip_services4_swagger的使用

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

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

该模块包含以下包：

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

使用

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

dependencies:
  pip_services4_swagger: version

现在你可以从命令行安装包：

flutter pub get

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

class MyRestController extends RestController {
  MyRestController() : 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/controllers/mycontroller.yml');
  }
}

为服务准备Open API规范，可以通过手动编写或使用Swagger编辑器完成。

openapi: '3.0.2'
info:
  title: 'MyService'
  description: 'MyService REST API'
  version: '1'
paths:
  /myservice/greeting:
    get:
      tags:
        - myservice
      operationId: 'greeting'
      parameters:
      - name: trace_id
        in: query
        description: Trace 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'

将Swagger服务包含在config.yml文件中，并为你的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_services4_container/pip_services4_container.dart';
import 'package:pip_services4_swagger/pip_services4_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

然后使用链接打开Swagger UI：

http://localhost:8080/swagger

结果应该类似于下图。

开发

对于开发，你需要安装以下前提条件：

• Dart SDK 3
• Visual Studio Code 或其他你选择的IDE
• Docker

安装依赖项：

flutter pub get

运行自动化测试：

flutter pub run test

生成API文档：

./docgen.ps1

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

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