标签: nestjs-swagger

这个 SO 答案表明，如果在实例化时传递端点，SwaggerUi 将按字母顺序对端点进行排序apisSorter : "alpha"。在 NestJS 中，配置选项在SwaggerModule.createDocument. 我看不到配置中的位置，例如在这里我可以通过它。

无法在路线中授权，@nestjs/swagger@5.0.9因为我以t know how to configure the 正确的方式使用 Document`，并且在授权官方文档/stackoverflow/github 中找不到可行的答案。

我偶然发现了 JWT 授权的问题。我正在使用"@nestjs/swagger": "^5.0.9"，在从公共路由获取访问令牌后，我将其插入到使用.addBearerAuth()方法配置的 swagger ui 字段“Authorize”中，在此版本（5.0.9）中具有此签名

addBearerAuth(options?: SecuritySchemeObject, name?: string)

与较低版本相反。

我已经在 Postman 中测试了我的 API，并且很容易获得授权，我还创建了一个交集，它在路由调用之前打印标头，但不幸的是它只在我调用公共路由时打印它们：/

我只知道邮递员正在设置一个不记名令牌，并且它会抛出路线，并且 swagger 没有发生类似的情况。

我已经尝试了很多这种配置的组合，但我还没有找到一个解决方案，结果我在我的路由方法中获得了授权，从 swagger 我无法访问它，因为 swagger 身份验证不是设置授权标头，以防配置错误或我做了完全错误的事情。我无法弄清楚。

a的配置addBearerAuth放在下面：

// swagger config
...
const config = new DocumentBuilder()
    .setTitle('SWAGGER API')
    .setVersion('1.0.0')
    .addBearerAuth(
      { 
        // I was also testing it without prefix 'Bearer ' before the JWT
        description: `[just text field] Please enter …

我有一个应用程序，我根据 open-api 规范将 API 响应模式定义为纯 JavaScript 对象。目前我将其传递给ApiResponse@nestjs/swagger 中的装饰器，如下所示：

class CatsController {

  @Get()
  @ApiResponse({
    status: 200,
    schema: catSchema // plain js object imported from another file
  })
  getAll() {}
}

这很好用。但是，输出 open-api 规范包含使用catSchema. 相反，我希望输出 swagger 文件在该部分下有 catSchema components，并$ref在 paths 部分中有一个对应的。

components:
  schemas:
    Cat:
      properties:
        name:
          type: string
paths:
  /cats/{id}:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cat'

到目前为止，唯一的方法似乎是将模式定义为 DTO 类并ApiProperty为每个类属性使用装饰器。就我而言，这意味着我必须将 open-api 规范中的所有普通对象模式重构为 DTO 类。

有没有办法将原始模式提供给库并获得预期的结果？

// instead of this:
class CatDto { …

我正在研究如何避免在每个 dto 中指定 @ApiProperty() 的方法。

我知道存在一种创建 file 的方法nest-cli.json，如果您Promise<DTO>在 Nest-swagger 的控制器中指定，它将从路由生成输出 dto 。

结构如下：

nest-cli.json

{
  "collection": "@nestjs/schematics",
  "sourceRoot": "src",
  "compilerOptions": {
    "plugins": [
      {
        "name": "@nestjs/swagger",
        "options": {
          "introspectComments": true
        }
      }
    ]
  }
}

controller.ts

@Get()
  async getMonitors (): Promise<OutputMonitorsDto> { // <-- Here is my outputDto
    return this.monitorsService.getMonitors()
  }

它大摇大摆地显示了这样的东西：

但是，有没有办法将 NestJs 设置为与 inputDTO 具有相同的内容，而不是在每个 dto 中写入@ApiProperty？

如下例所示：

ExampleDto.ts

export class GetListUsersDto {
  @ApiProperty()
  @IsString()
  name: string
  @ApiProperty()
  @IsString()
  email: string
  @ApiProperty() …

我正在构建一个具有公共 API 和内部 API 的应用程序。我想将这些文档发布到不同的路线。我认为这可以通过仅向文档（addTag）添加某些标签来完成，但经过进一步阅读和实验后，它并没有完成这项工作。

文档始终包含所有内容，所有模块的所有记录端点。

这可能吗？如果是这样，怎么办？

我不认为代码是必要的，但 FWIW：

const pubOptions = new DocumentBuilder()
    .setTitle('Pub API Docs')
    .setDescription('Blah blah API documentation')
    .setVersion(p.version)
    .addBearerAuth()
    .addTag('public-app')
    .build();
const document = SwaggerModule.createDocument(app, pubOptions);
SwaggerModule.setup('public-api', app, document);

const internalOptions = new DocumentBuilder()
    .setTitle('Internal API Docs')
    .setDescription('Blah blah API documentation')
    .setVersion(p.version)
    .addBearerAuth()
    .addTag('internal')
    .build();
const iDocument = SwaggerModule.createDocument(app, internalOptions);
SwaggerModule.setup('internal-api', app, iDocument);

我正在开发一个 Nestjs 项目，我添加了 swagger 来显示我的端点，它在开发模式下工作得很好，但是一旦使用https://zeit.co/（现在）部署在生产中，端点页面就无法正确显示（缺少 css），我在网络选项卡中收到此错误：

/favicon-32x32.png:1 Failed to load resource: the server responded with a status of 404 ()
/favicon-16x16.png:1 Failed to load resource: the server responded with a status of 404 ()
swagger-ui.css:1 Failed to load resource: the server responded with a status of 404 ()

https://i.stack.imgur.com/T9IQv.png

谢谢。

我正在根据此文档在我的小型 Nest.js 应用程序中设置 swagger 文档：https ://docs.nestjs.com/recipes/swagger

如何设置 dto 以在 swagger 中正确显示架构？更具体地说，嵌套类型。它只显示顶级键。如果其中一个键是某种类型的东西，它就将它显示为空对象。这就是我的意思：

dto:

export class HealthCheckDataDto {
    serverStatus: {} // dont have it typed yet;
    dbStatus: MongoConnectionStateT;
} 

昂首阔步：

[
  {
    "serverStatus": {},
    "dbStatus": {}
  }
]

swagger 示例值中的预期结果：

[
  {
    "serverStatus": {},
    "dbStatus": {
      "isOnline": true,
      "msg": "string"
    }
  }
]

这是函数：

@ApiResponse({ status: 200, description: 'blabla', type: [HealthCheckDataDto] })
@ApiResponse({ status: 500, description: 'blabla, but bad', type: [HealthCheckDataDto] })
@Get('/api/healthcheck')
healthCheckApp(@Res() res: Response<HealthCheckDataDto>) {

    // check HCs and …

我有一个带有 Nest.js API 和 Angular SPA 的项目。SPA 用于与 API 通信的 DTO 位于一个名为 Models 的单独项目中，我将其用作依赖项。这样，我只需在一处更改 DTO，就可以在两个项目中重用它们。

我一直在尝试使用 Swagger 来记录我的 API @nestjs/swagger。如果我希望在 Swagger 中显示 DTO 的属性，则该库要求我在 DTO 中使用装饰器。

当我这样做时，API 中的一切都按预期工作，但 Angular SPA 会崩溃，因为它没有依赖性@nestjs/swagger。即使将其安装为应用程序的依赖项后，它仍然需要我安装@nestjs/common、express、mime、send等，并且我不应该仅仅为了文档而将所有这些后端相关依赖项安装到我的应用程序中。

你们知道如何克服这个问题或有关使用 Nest.js 生成 API 文档的其他技巧吗？

我想向我的 dto 添加一个描述字段（也是为了满足no_schema_descriptionOpenAPI linting），但找不到这样做的方法。使用哪个装饰器？在定义 dto 时还是在响应中？

更新（澄清）：我希望定义整个架构的描述，而不是单个属性的描述。

I have this route which can return one of these two different DTOs:

  @Get()
  @ApiQuery({ name: 'legacy', description: "'Y' to get houses legacy" })
  async findAllHouses(
    @Query('legacy') legacy: string,
  ): Promise<HousesDto[] | HousesLegacyDto[]> {
  ...
  }

I want to display both of these ResponseDTOs in swagger. I've tried this decorator:

  @ApiOkResponse({
    schema: { oneOf: refs(HousesDto, HousesLegacyDto) },
  })
// OR
  @ApiOkResponse({
    schema: {
      oneOf: [
        { $ref: getSchemaPath(HousesDto) },
        { $ref: getSchemaPath(HousesLegacyDto) },
      ],
    },
  })

with @ApiExtraModels() on …