Openapi
其他功能
了解 @nestjs/swagger 的其他有用功能，包括全局前缀、全局参数、全局响应、多规范支持和资源管理器栏下拉菜单配置。
其他功能
本页列出了您可能会发现有用的所有其他可用功能。
全局前缀
要忽略通过 setGlobalPrefix() 设置的路由全局前缀，请使用 ignoreGlobalPrefix：
const document = SwaggerModule.createDocument(app, options, {
ignoreGlobalPrefix: true,
});
全局参数
您可以使用 DocumentBuilder 为所有路由定义参数，如下所示：
const config = new DocumentBuilder()
.addGlobalParameters({
name: 'tenantId',
in: 'header',
})
// 其他配置
.build();
全局响应
您可以使用 DocumentBuilder 为所有路由定义全局响应。这对于在应用程序的所有端点中设置一致的响应非常有用，例如 401 Unauthorized 或 500 Internal Server Error 等错误代码。
const config = new DocumentBuilder()
.addGlobalResponse({
status: 500,
description: 'Internal server error',
})
// 其他配置
.build();
多规范
SwaggerModule 提供了一种支持多规范的方法。换句话说，您可以在不同的端点上提供不同的文档和不同的 UI。
要支持多规范，您的应用程序必须采用模块化方法编写。createDocument() 方法接受第三个参数 extraOptions，这是一个具有名为 include 属性的对象。include 属性接受一个值，该值是模块数组。
您可以按如下所示设置多规范支持：
import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { AppModule } from './app.module';
import { CatsModule } from './cats/cats.module';
import { DogsModule } from './dogs/dogs.module';
async function bootstrap() {
const app = await NestFactory.create(AppModule);
/**
* createDocument(application, configurationOptions, extraOptions);
*
* createDocument 方法接受一个可选的第三个参数 "extraOptions"
* 这是一个具有 "include" 属性的对象，您可以在其中传递一个
* 您想要包含在该 Swagger 规范中的模块数组
* 例如：CatsModule 和 DogsModule 将有两个独立的 Swagger 规范，
* 它们将在两个不同的 SwaggerUI 上以两个不同的端点公开。
*/
const options = new DocumentBuilder()
.setTitle('Cats example')
.setDescription('The cats API description')
.setVersion('1.0')
.addTag('cats')
.build();
const catDocumentFactory = () =>
SwaggerModule.createDocument(app, options, {
include: [CatsModule],
});
SwaggerModule.setup('api/cats', app, catDocumentFactory);
const secondOptions = new DocumentBuilder()
.setTitle('Dogs example')
.setDescription('The dogs API description')
.setVersion('1.0')
.addTag('dogs')
.build();
const dogDocumentFactory = () =>
SwaggerModule.createDocument(app, secondOptions, {
include: [DogsModule],
});
SwaggerModule.setup('api/dogs', app, dogDocumentFactory);
await app.listen(process.env.PORT ?? 3000);
}
bootstrap();
现在您可以使用以下命令启动服务器：
$ npm run start
导航到 http://localhost:3000/api/cats 查看 cats 的 Swagger UI：
反过来，http://localhost:3000/api/dogs 将公开 dogs 的 Swagger UI：
资源管理器栏中的下拉菜单
要在资源管理器栏的下拉菜单中启用对多规范的支持，您需要设置 explorer: true 并在 SwaggerCustomOptions 中配置 swaggerOptions.urls。
info 提示 确保
swaggerOptions.urls指向您的 Swagger 文档的 JSON 格式！要指定 JSON 文档，请在SwaggerCustomOptions中使用jsonDocumentUrl。有关更多设置选项，请查看此处。
以下是如何从资源管理器栏的下拉菜单设置多规范：
import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { AppModule } from './app.module';
import { CatsModule } from './cats/cats.module';
import { DogsModule } from './dogs/dogs.module';
async function bootstrap() {
const app = await NestFactory.create(AppModule);
// 主 API 选项
const options = new DocumentBuilder()
.setTitle('Multiple Specifications Example')
.setDescription('Description for multiple specifications')
.setVersion('1.0')
.build();
// 创建主 API 文档
const document = SwaggerModule.createDocument(app, options);
// 设置支持下拉菜单的主 API Swagger UI
SwaggerModule.setup('api', app, document, {
explorer: true,
swaggerOptions: {
urls: [
{
name: '1. API',
url: 'api/swagger.json',
},
{
name: '2. Cats API',
url: 'api/cats/swagger.json',
},
{
name: '3. Dogs API',
url: 'api/dogs/swagger.json',
},
],
},
jsonDocumentUrl: '/api/swagger.json',
});
// Cats API 选项
const catOptions = new DocumentBuilder()
.setTitle('Cats Example')
.setDescription('Description for the Cats API')
.setVersion('1.0')
.addTag('cats')
.build();
// 创建 Cats API 文档
const catDocument = SwaggerModule.createDocument(app, catOptions, {
include: [CatsModule],
});
// 设置 Cats API Swagger UI
SwaggerModule.setup('api/cats', app, catDocument, {
jsonDocumentUrl: '/api/cats/swagger.json',
});
// Dogs API 选项
const dogOptions = new DocumentBuilder()
.setTitle('Dogs Example')
.setDescription('Description for the Dogs API')
.setVersion('1.0')
.addTag('dogs')
.build();
// 创建 Dogs API 文档
const dogDocument = SwaggerModule.createDocument(app, dogOptions, {
include: [DogsModule],
});
// 设置 Dogs API Swagger UI
SwaggerModule.setup('api/dogs', app, dogDocument, {
jsonDocumentUrl: '/api/dogs/swagger.json',
});
await app.listen(3000);
}
bootstrap();
在此示例中，我们设置了一个主 API 以及 Cats 和 Dogs 的独立规范，每个都可以从资源管理器栏的下拉菜单中访问。