@pagoda-tools/swagger-ui

安装

# install npm
npm install @pagoda-tools/swagger-ui -S

# install yarn
yarn add @pagoda-tools/swagger-ui -S

文档编写示例

1. 根目录新增配置文件 swagger.config.js

import { defineSwaggerConfig } from '@pagoda-tools/swagger-ui';

export default defineSwaggerConfig({
  info: {
    title: '测试文档标题',
    version: '1.0.0',
  },
  server: [
    {
      url: 'http://www.xxx.com',
      description: '测试环境',
    },
  ],
});

2. 在 src 任意目录下新建 xx.dto.ts，示例代码如下：

import {
  defineSwaggerConfig,
  defineSwaggerApi,
  IsInt,
  IsString,
  Type,
  ValidateNested,
} from '@pagoda-tools/swagger-ui';

class User {
  @IsString()
  name: string;
}

export class TestInput {
  @IsInt()
  @JSONSchema({
    description: '字段描述',
  })
  a: number;

  @ValidateNested({ each: true })
  @Type(() => User)
  @JSONSchema({
    description: '字段描述',
  })
  users: User[];
}

export class TestOutput {
  @IsInt()
  a: number;
}

export default defineSwaggerApi({
  method: 'get',
  summary: '接口名称',
  input: TestInput,
  output: TestOutput,
});

3. 在 package.json 的 scripts 中新增命令

{
  "scripts": {
    "doc-serve": "pd-swagger-ui serve",
    "export-doc-json": "pd-swagger-ui json"
  }
}

4. 执行 npm run doc-serve

swagger.config.js 配置项

interface SwaggerConfig {
  info?: {
    // 文档标题
    title?: string;
    // 文档描述
    description?: string;
    // 文档版本
    version?: string;
  };
  server?: {
    // 接口环境地址
    url: string;
    // 接口环境地址描述
    description?: string;
  }[];
}

• IsInt 等修饰器参考 class-validator