如何在不运行应用程序的情况下使用nestjs生成openapi规范 [英] How to generate openapi specification with nestjs without running the application

问题描述

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

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

感谢您的帮助

推荐答案

简短的答案是不，there isn't a way to generate the docs不运行NestJS应用程序。但是，您可以生成一个表示openapi文档的json文件，然后从那里生成一个静电网站。This issue半途而废：

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();

这将生成一个包含OpenAPI规范的文件swagger.json。在那里，您可以使用tool like Spectacle生成实际的HTML：

npx spectacle-docs -t public/docs swagger.json

一个文档更少的功能是仅使用cURL从常规端点检索OpenAPI规范的JSON表示。

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

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

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

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

script:
  - until nc -vz $API_IP 3000; do sleep 1; done
  - curl http://$API_IP:3000/docs-json -o swagger.json
  - npx spectacle-docs -t public/docs swagger.json

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

这篇关于如何在不运行应用程序的情况下使用nestjs生成openapi规范的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！