Skip to main content

在Backstage插件中开始使用 OpenAPI

目标受众： 插件开发人员

难度： 中等

目标​

本教程的目的是让您了解如何将 OpenAPI 规范与插件生命周期更紧密地结合起来。 我们将介绍的工具由 OpenAPI 工具项目区创建，允许您创建、

1.一个类型化的 "express "路由器，可在开发过程中为输入和输出值提供强大的防护，支持查询、路径参数和请求正文，并试验性地支持标头和 cookie。 2.一个自动生成的客户端，可与插件后端进行交互，支持所有请求类型、参数和正文以及返回类型，提供一个底层接口，允许更高级别的库进行更多定制。 3.验证和校验工具，可确保您的 API 和规范保持同步，包括针对单元测试的测试。

先决条件​

技术知识​

本教程假定您已经熟悉以下内容、

  1. 如何构建 Backstage 插件 2. Express.js 和 Typescript 3. OpenAPI 3.0 模式

设置​

在开始之前，我们需要安装两个 npm 软件包、

  1. @backstage/repo-tools，这个软件包包含所有与插件 OpenAPI 相关的命令。 我们将在整个教程中使用它。 2. @opticdev/optic，这个软件包是 @backstage/repo-tools的依赖包，但只需要与 OpenAPI 相关的命令。

您应该将上述两个软件包安装在根的工作空间。

存储 OpenAPI 规范​

您应该创建一个新文件夹、src/schema在后端插件中存储 OpenAPI(和其他)规范。 例如，如果您要向目录插件添加规范，您可以添加一个src/schema文件夹转到plugins/catalog-backend，使plugins/catalog-backend/src/schema该目录应包含一个openapi.yaml里面的文件。

目前只支持 .yaml 扩展名，不支持 .yml。

从规范生成类型化的表达式路由器​

运行yarn backstage-repo-tools schema openapi generate <plugin-directory>这将创建一个openapi.generated.ts文件中的src/schema目录，其中包含 OpenAPI 模式以及生成的带有类型的 express 路由器。

像这样使用它，更新您的router.ts或createRouter.ts文件，内容如下

+ import { createOpenApiRouter } from '../schema/openapi.generated';
- import Router from 'express-promise-router';

...
export async function createRouter(
  options: RouterOptions,
): Promise<express.Router> {
+ const router = await createOpenApiRouter();
- const router = Router();

从规范生成类型化客户端​

运行yarn backstage-repo-tools schema openapi generate-client --input-spec <plugin-directory>/src/schema/openapi.yaml --output-directory <plugin-client-directory>.<plugin-directory>应与我们目前一直使用的后端插件一致。<plugin-client-directory>是您应该创建的新目录和 npm 软件包。 一般模式是plugins/<plugin-name>-client.

生成的客户端将有一个目录src/generated输出一个DefaultApiClient您可以像这样使用客户端、

+ import { DefaultApiClient } from './generated';

export class CatalogClient implements CatalogApi {
+ private readonly apiClient: DefaultApiClient;

  constructor(options: {
    discoveryApi: { getBaseUrl(pluginId: string): Promise<string> };
    fetchApi?: { fetch: typeof fetch };
  }) {
+    this.apiClient = new DefaultApiClient(options);
  }
  ...

类型的使用取决于您的类型名称。

您应该可以使用生成的DefaultApi.client.ts要实现完全定制，可以使用生成客户端的包装器来调整客户端的风格。

更多信息，请参见文档.

使用测试流量验证规格​

在您的createRouter.test.ts或router.test.ts锉刀

+ import { wrapInOpenApiTestServer } from '@backstage/backend-openapi-utils';
+ import { Server } from 'http';

...

describe('createRouter', () => {
- let app: express.Express;
+ let app: express.Express | Server;

...

- app = express().use(router);
+ app = wrapInOpenApiTestServer(express().use(router));

这就为 express 服务器添加了一个封装，使其能够为supertest运行yarn backstage-repo-tools schema openapi init来创建一些所需的配置文件。 现在，当您运行yarn backstage-repo-tools schema openapi test任何错误都会被报告。

我们的命令是对光学它能完成所有繁重的工作。

更多信息，请参见文档.