# @atlaslabs/koa-swagger-decorator 中文文档

规范地址：https://npmcn.com/package/%40atlaslabs/koa-swagger-decorator/

版本：0\.2\.118
npm 元数据更新时间：2022-04-04T16:11:47.540Z
中文译文更新时间：2026-11-07T03:09:13.421Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40atlaslabs/koa-swagger-decorator
原文对照：https://npmcn.com/package/%40atlaslabs/koa-swagger-decorator/?lang=original
项目主页：https://github.com/goodatlas/switch-backend.modules#readme
源码仓库：https://github.com/goodatlas/switch-backend.modules

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：106 kB，27 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：7 个
- 首次发布：2020-03-13T02:44:16.931Z
- 最新版本发布：2021-12-02T01:07:17.892Z
- 近 30 天下载量：9305（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 0 个）

## 中文简介

使用装饰器自动生成 ka- routter 的 swagger doc

## 安装

```sh
npm install @atlaslabs/koa-swagger-decorator
```

也可以使用：`pnpm add @atlaslabs/koa-swagger-decorator`、`yarn add @atlaslabs/koa-swagger-decorator`、`bun add @atlaslabs/koa-swagger-decorator`

## README

# 科阿-斯瓦格-代号

> 使用装饰器自动生成 swagger json 文件

[![build status](https://travis-ci.org/Cody2333/koa-swagger-decorator.svg?branch=develop)](https://travis-ci.org/Cody2333/koa-swagger-decorator) [![npm](https://img.shields.io/npm/l/express.svg)](https://www.npmjs.com/package/koa-swagger-decorator)

## 安装

```bash
npm install koa-swagger-decorator
```

## 贡献指南

请参考 [捐款](https://github.com/Cody2333/koa-swagger-decorator/blob/master/CONTRIBUTING.md) 在创建您的公关或问题之前.

## 导言

### Koa Swagger 装饰器

使用装饰器自动生成 swagger json docs 为 swagger 定义添加支持验证

基于 [Swagger OpenAPI 规格 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md)

支持 javascript (需要的babel) 和打字符

## 示例

```bash
// using commonds below to start and test the example server

git clone https://github.com/Cody2333/koa-swagger-decorator.git

cd koa-swagger-decorator

npm install

npm run start

finally open:
http://localhost:3000/api/swagger-html
```

### 所需资源

-   科亚2
-   旋转道
-   装饰器的 bail 支持( 或使用打字符)

```bash
// add [transform-decorators-legacy] to .babelrc if using js

npm install --save-dev babel-plugin-transform-decorators-legacy

{
  "presets": [
    ["env", {"targets": {"node": "current"}}]
  ],
  "plugins": ["transform-decorators-legacy"]
}
```

### 细节

详情请看 [例 koa 服务器](https://github.com/Cody2333/koa-swagger-decorator/tree/master/example)

#### 将 koa 路由对象先包裹

```javascript
// router.js
import Router from 'koa-router'

import Test from './test'

import { SwaggerRouter } from 'koa-swagger-decorator'

const router = new SwaggerRouter([KoaRouterOpts],[SwaggerOpts]) // extends from koa-router

// swagger docs avaliable at http://localhost:3000/api/swagger-html
router.swagger({
  title: 'Example Server',
  description: 'API DOC',
  version: '1.0.0',

  // [optional] default is root path.
  // if you are using koa-swagger-decorator within nested router, using this param to let swagger know your current router point
  prefix: '/api',

  // [optional] default is /swagger-html
  swaggerHtmlEndpoint: '/swagger-html',

  // [optional] default is /swagger-json
  swaggerJsonEndpoint: '/swagger-json',

  // [optional] additional options for building swagger doc
  // eg. add api_key as shown below
  swaggerOptions: {
    securityDefinitions: {
      api_key: {
        type: 'apiKey',
        in: 'header',
        name: 'api_key',
      },
    },
  },
  // [optional] additional configuration for config how to show swagger view
  swaggerConfiguration: {
    display: {
      defaultModelsExpandDepth: 4, // The default expansion depth for models (set to -1 completely hide the models).
      defaultModelExpandDepth: 3, // The default expansion depth for the model on the model-example section.
      docExpansion: 'list', // Controls the default expansion setting for the operations and tags. 
      defaultModelRendering: 'model' // Controls how the model is shown when the API is first rendered. 
    }
  }
})
// map all static methods at Test class for router
// router.map(Test);

// mapDir will scan the input dir, and automatically call router.map to all Router Class
router.mapDir(_path.resolve(__dirname), {
  // default: true. To recursively scan the dir to make router. If false, will not scan subroutes dir
  // recursive: true,
  // default: true, if true, you can call ctx.validatedBody[Query|Params] to get validated data.
  // doValidation: true,
  // default: [], paths to ignore while looking for decorators 
  // ignore: ["**.spec.ts"],
})
```

#### 使用装饰器制作 api 定义

```javascript
// test.js

import User from 'models/user'
import { request, summary, query, path, body, tags } from 'koa-swagger-decorator'

const testTag = tags(['test'])

const userSchema = {
  name: { type: 'string', required: true },
  gender: { type: 'string', required: false, example: 'male' },
  groups: {
    type: 'array',
    required: true,
    items: { type: 'string', example: 'group1' }, // item's type will also be validated
  },
}

export default class Test {
  @request('get', '/users')
  @summary('get user list')
  @security([{ api_key: [] }])
  @testTag
  @query({
    type: { type: 'number', required: true, default: 1, description: 'type' },
  })
  static async getUsers(ctx) {
    const users = await User.findAll()
    ctx.body = { users }
  }

  @request('get', '/users/{id}')
  @summary('get user info by id')
  @security([{ api_key: [] }])
  @testTag
  @path({
    id: { type: 'number', required: true, default: 1, description: 'id' },
  })
  static async getUser(ctx) {
    const { id } = ctx.validatedParams
    const user = await User.findById(id)
    ctx.body = { user }
  }

  @request('post', '/users')
  @testTag
  @body(userSchema)
  static async postUser(ctx) {
    // const body = ctx.request.body;
    const body = ctx.validatedBody
    ctx.body = { result: body }
  }

  static async temp(ctx) {
    ctx.body = { result: 'success' }
  }
}
```

#### 使用装饰来制作 api 体

```typescript
import Router from 'koa-router';
import { request, summary, query, path, body, tags, swaggerClass, swaggerProperty } from 'koa-swagger-decorator'

@swaggerClass()
export class subObject {
  @swaggerProperty({ type: "string", required: true }) Email: string = "";
  @swaggerProperty({ type: "string", required: true }) NickName: string = "";
  @swaggerProperty({ type: "string", required: true }) Password: string = "";
};

@swaggerClass()
export class userInfo {
  @swaggerProperty({ type: "string", required: true }) Email: string = "";
  @swaggerProperty({ type: "string", required: true }) NickName: string = "";
  @swaggerProperty({ type: "string", required: true }) Password: string = "";
  @swaggerProperty({type:"object",properties:(subObject as any).swaggerDocument}) UserInfo:subObject;
};

export default class Test {
  @request('POST', '/user/Register')
  @summary('register user')
  @description('example of api')
  @body((userInfo as any).swaggerDocument)
  static async Register(ctx: Router.IRouterContext) {
    var params = (ctx as any).validatedBody as userInfo;
    console.log(params);
  }
}
```

#### 可验证说明

-   标记
-   查询
-   路径
-   机构
-   窗体数据
-   中间软件
-   警卫
-   目录
-   说明
-   答复
-   已贬值

#### 类说明

-   标记全部
-   回复
-   中间软件
-   全部安全
-   全部贬值
-   全部查询

```javascript
request // @request('POST', '/users')

tags // @tags(['example'])
query // @query({limit: {type: 'number', required: true, default: 10, description: 'desc'}})

path // @path({limit: {type: 'number', required: true, default: 10, description: 'desc'}})

body // @body({groups: {type: 'array', required: true, items: { type: 'string', example: 'group1' }}})

formData // @formData({file: {type: 'file', required: true, description: 'file content'}})

middlewares
// support koa middlewares.
// eg. @middlewares([func1,func2])

security 
// define authentication method, key must be same as one of methods defined in swaggerOptions.securityDefinitions
// @security([{ api_key: [] }]) 

summary // @summary('api summary')

description // @description('api description')

responses
// @responses({ 200: { description: 'success'}, 400: { description: 'error'}})
// responses is optional

deprecated // @deprecated

@tagsAll(['A', 'B'])
@deprecatedAll
@securityAll([{ api_key: [] }])
@middlewaresAll([log1, log2]) // add middlewares [log1, log2] to all routers in this class
@queryAll({ limit: { type: 'number', default: 444, required: true } }) // can be merged with @query
export default class SampleRouter {
  ...
}
```

#### 验证

支持验证类型 : `string, number, boolean, object, array.`

`properties` 内 `{type: 'object'}` 财务报告和审定财务报表 `items` 内 `{type: 'array'}` 还可以验证.

其他类型,例如:. `integer` 将不会被验证,并将返回原始值.

默认情况下,验证被激活,您可以调用 ctx.validatedQuery \[Body|Params\] 访问已验证值.

以关闭验证 :

```javascript
router.mapDir(_path.resolve(__dirname), {
  // default: true, if true, you can call ctx.validatedBody[Query|Params] to get validated data.
  doValidation: false,
})
```

##### 运行此工程, 它会通过 swagger ui 生成文件

![image.png](http://upload-images.jianshu.io/upload_images/2563527-4b6ed895183a0055.png?imageMogr2/auto-orient/strip%7CimageView2/2/w/1240)

## 许可证

麻省理工学院

## 常见问题

### @atlaslabs/koa-swagger-decorator 是什么？

使用装饰器自动生成 ka- routter 的 swagger doc

### 如何安装 @atlaslabs/koa-swagger-decorator？

在项目目录运行 npm install @atlaslabs/koa-swagger-decorator，或使用 pnpm add / yarn add / bun add。

### @atlaslabs/koa-swagger-decorator 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/atlaslabs\_\_koa-swagger-decorator 是否存在。

### @atlaslabs/koa-swagger-decorator 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @atlaslabs/koa-swagger-decorator 可以商用吗？

@atlaslabs/koa-swagger-decorator 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @atlaslabs/koa-swagger-decorator 的下载量有多少？

根据 npm 官方下载统计，@atlaslabs/koa-swagger-decorator 在 2026/10/07 – 2026/11/05 这 30 天内被下载 9,305 次，日均约 310 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @atlaslabs/koa-swagger-decorator 还在维护吗？

最新版本 0\.2\.118 发布于 2021/12/02（4 年前）；至今共发布 10 个版本，其中过去 12 个月发布了 0 个；首次发布于 2020/03/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。