# @pagoda-tools/swagger-ui

## 安装

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

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

## 文档编写示例

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

```ts
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`，示例代码如下：

```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` 中新增命令

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

4. 执行 `npm run doc-serve`

### swagger.config.js 配置项

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

- `IsInt` 等修饰器参考 [class-validator](https://github.com/typestack/class-validator#validation-decorators)