@ chax-at/ swagger- helpers-nest (帮助者)

这个软件包提供了额外的生成工具 打开API 文档 雀巢JS/斯瓦格 简单点.

使用量

先决条件

首先,通过运行安装软件包

npm i @chax-at/swagger-helpers-nest

装饰者

为了有更好的时间生成有用的OpenAPI(swagger) doc文件,这个包提供了一套将@nestjs/swagger装饰器组合在一起的装饰器.

以下是一些例子.

DTO 属性

class MugResponse {
  // if a property can have one of multiple types, use
  @ApiPropertyOneOf(TeaDto, CoffeeDto)
  public contents!: TeaDto | CoffeeDto;
}

class CarResponse {
  // if a property is an array of one or more non-primitive types, use
  @ApiPropertyArrayOf(WheelDto)
  public wheels!: WheelDto[];
}

class SuccessResponse {
  // if a property must be one specific value rather than a type, use
  @ApiPropertyOfValue(true)
  public success!: true;
}

class StatusResponse {
  // if a property's value is an enum, use the following to export the enum itself into the docs too
  @ApiPropertyEnum({ Status })
  public status!: Status;
}

回应

class DrinksController {
  @Get()
  // if a route can have one of multiple response types, use
  @ApiResponseOneOf([TeaResponse, CoffeeResponse])
  public getDrink(): Promise<TeaResponse | CoffeeResponse> {
    return this.drinkService.getDrinkResponse();
  }

  @Post()
  // if a route can have one of multiple response types and the status should be 201, use
  @ApiCreatedResponseOneOf([TeaResponse, CoffeeResponse])
  public createDrink(): Promise<TeaResponse | CoffeeResponse> {
    return this.drinkService.createDrink();
  }
}

员额处理

有时候装潢师只是不切 之后你想做出改变 @nestjs/swagger是因为 buildSwaggerDocument() 结束了.

对于此, 此软件包提供了一个倒转功能 traverseDocument 可以配置访问者.

示例

const MyVisitor: SchemaVisitor = (schema) => {
  if (matchesSomeCondition(schema)) {
    // modify schema in place
  }
};

const document = buildSwaggerDocument(app);
traverseDocument(document, {
  propertyVisitors: [
    Length1AllOfToOneOfVisitor, // convert allOf's with one entry to oneOf's
    MoveNullableToOneOfVisitor, // move a nullable:true into a sibling oneOf
    MyVisitor, // your own
  ],
  operationVisitors: [
    // an example visitor that adds an operation's method as a tag
    (op, method) => {
      op.tags.push(method);
    },
    // an example visitor that removes operations based on a tag
    (op) => {
      if (op.tags?.include('DoNotExpose')) {
        return 'delete';
      }
    },
  ],
});