如何在不运行应用程序的情况下使用nestjs生成openapi规范

Question

我们有很多用nodejs编写的API，使用nestjs框架。我们可以使用 Nestjs 中的 SwaggerModule 生成 openapi.yaml。效果很好。但问题是它需要 API 启动，因此数据库启动并运行。这对我们的 CI/CD 来说是一个问题，因为我们需要在运行 API 之前生成 openapi 规范。

是否可以从我们的代码生成 openapi 规范，而不需要运行应用程序？或者也许有一种简单的方法来模拟我们的数据库？

感谢您的帮助

Answer 1

简短的回答是否定的，没有办法在不运行 NestJS 应用程序的情况下生成文档。但是，您可以生成表示 OpenAPI 文档的 JSON 文件，然后从那里生成静态网站。这个问题让你成功了一半：

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const options = new DocumentBuilder()
    .setTitle('Cats example')
    .setDescription('The cats API description')
    .setVersion('1.0')
    .addTag('cats')
    .build();
  const document = SwaggerModule.createDocument(app, options);
  const outputPath = path.resolve(process.cwd(), 'swagger.json');
  writeFileSync(outputPath, JSON.stringify(document), { encoding: 'utf8'});

  await app.close();
}
bootstrap();

这将生成一个swagger.json包含 OpenAPI 规范的文件。从那里，您可以使用像 redocly 这样的工具来生成实际的 HTML：

npx @redocly/cli build-docs -o public/docs swagger.json

一个记录较少的功能是仅使用curl 从常规端点检索 OpenAPI 规范的 JSON 表示的能力。

假设您有一个标准的 @nestjs/swagger 集成，它将 OpenAPI 文档发布到/docs/：

npx @redocly/cli build-docs -o public/docs swagger.json

如果您浏览到http:/localhost:3000/docs/，您可以访问该文档的 HTML 版本。但是，如果您浏览，http://localhost:3000/docs-json您将收到 JSON 表示形式。只需附加-json到您指定的路径即可。

将所有这些结合在一起，您可以通过一些技巧将其集成到 CI 管道中。我已将其集成到 Gitlab CI 管道中，如下所示：

  const options = new DocumentBuilder()
    .setTitle('core-api')
    .setDescription('The core API description')
    .setVersion('3.0')
    .addTag('core-api')
    .setBasePath(version)
    .build();
  const document = SwaggerModule.createDocument(app, options);
  SwaggerModule.setup('docs', app, document);

在 CI 管道中，您仍然需要运行 NestJS 应用程序以及 Mongo 和启动所需的任何其他依赖服务，但是一旦生成 JSON，您就可以停止应用程序、构建静态 HTML 站点并发布它在别处。