Swagger

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。Swagger 让部署管理和使用功能强大的 API 从未如此简单。

Midway 通过组件化的形式来支持 swagger 能力。

一、例子#

$ npm install$ npm run dev

然后访问：http://127.0.0.1:7001/swagger-ui/index.html

二、使用方法#

2.1 安装#

安装依赖。

npm install @midwayjs/swagger --savenpm install swagger-ui-dist --save-dev

如果想要在服务器上输出 swagger API 页面，则需要将 swagger-ui-dist 安装到依赖中。

npm install swagger-ui-dist --save

2.2 配置#

在 configuration.ts 中增加组件。

import { Configuration } from '@midwayjs/decorator';import * as swagger from '@midwayjs/swagger';
@Configuration({  imports: [swagger],})export class ContainerConfiguration {}

可以配置启用的环境，比如下面的代码指的是“只在 local 环境下启用”。

import { Configuration } from '@midwayjs/decorator';import * as swagger from '@midwayjs/swagger';
@Configuration({  imports: [    {      component: swagger,      enabledEnvironment: ['local'],    },  ],})export class ContainerConfiguration {}

2.3 使用#

直接启动即可，由于通过元数据进行了分析，默认情况下，可以直接获取到当前的参数，类型，名称，依赖关系等。

访问：http://127.0.0.1:7001/swagger-ui/index.html 拿到 swagger UI 界面。访问：http://127.0.0.1:7001/swagger-ui/json 拿到 swagger json 结构。

三、示例#

3.1 描述请求#

通过 summary 和 description 方法，我们可以对整个接口进行描述。

import { CreateApiDoc } from '@midwayjs/swagger'
@CreateApiDoc()  .summary('get user')  .description('This is a open api for get user')  .build()
@Get('/:userId')async getUser(@Param() userId: number, @Query() name?: string) {  return {    name: 'harry',    age: 18  };}

3.2 参数描述#

通过 param 方法可以描述接口的参数，按顺序描述参数。如果有多个参数，则可以调用多次。以我们的示例为例，有两个参数， userId 和 name 。

param 方法的定义如下。

param(description: Partial<APIParamFormat>): SwaggerAPI;param(description: string, options?: Partial<APIParamFormat>): SwaggerAPI;

在最简单的情况下，我们可以直接写参数的描述，同时，会自动分析出参数的类型，比如路由中的参数、请求中的参数等。

@CreateApiDoc()    .param('user id')    .param('user name')  .build()
@Get('/:userId')async getUser(@Param() userId: number, @Query() name?: string) {  return {    name: 'harry',    age: 18  };}

在更为复杂的情况下，参数可以更加精确的描述。

export interface APIParamFormat {  name: string; // 参数名  description: string; // 参数描述  required: boolean; // 参数是否必须  deprecated: boolean; // 参数是否废弃  allowEmptyValue: boolean; // 参数是否允许控制  example: any; // 参数的示例}

下面是参数的示例，有两种方式去具体描述参数。

@CreateApiDoc().summary('get user').description('This is a open api for get user').param('user id', {  required: true,  example: '123456'}).param({  description: 'This is a user name'}).build()@Get('/:userId')async getUser(@Param() userId: number, @Query() name?: string) {  return {    name: 'harry',    age: 18  };}

3.3 返回值描述#

一个接口会有多种返回值的可能性，可以调用多次 respond 方法来描述不同的返回结果。

响应的接口描述如下。

respond(  status: number,  description?: string,  respondType?: string,  options?: Partial<APIResponseFormat>): SwaggerAPI;
export interface APIResponseFormat {  status: string;  description: string;  headers: any;  example: any;}

参数分为四个部分，除了状态码，其他都是可选参数，下面的示例展示了多种不同的返回描述。

@CreateApiDoc().summary('get user').description('This is a open api for get user').respond(200).respond(302, 'redirect to another URL').respond(201, 'response a text data', 'text', {  headers: {    'x-schema': {      description: 'set a schema header',      type: 'string'    }  },  example: 'this is a reponse data'}).respond(500, 'error in response', 'json', {  example: {    a: 1  }}).build()

你可以直接设置一个状态码，也可以在设置状态码之后，紧跟着设置描述，以及返回的 header，数据类型和示例。

展示的效果为

3.4 通用描述#

可以通过在 Controller 装饰器和 Get 等路由装饰器上简单的增加描述信息。

控制器分组和描述#

@Controller('/', { tagName: 'Custom Group', description: 'Home Router' })export class HomeController {}

路由描述#

@Get('/', {summary: 'Main Page', description: 'This is a home router'})async home() {  return 'Hello Midwayjs!';}

增强的接口描述信息（进阶模式）#

如果需要增加细节描述字段，则增加了 @CreateApiDoc 装饰器，用于定义描述，包括入参和出参。整个装饰器设计为链式调用，方便 IDE 获取到对应的方法和参数定义。

我们以一个接口为例。注意， @CreateApiDoc 装饰器最后需要跟一个 build 方法作为结尾。

完整的示例

import { CreateApiDoc, CreateApiPropertyDoc } from '@midwayjs/swagger';
export class UserDTO {  @CreateApiPropertyDoc('user name')  @Rule(RuleType.string().required())  name: string;
  @CreateApiPropertyDoc('user age')  @Rule(RuleType.number())  age: number;}
@Provide()@Controller('/user')export class UserController {  @Inject()  ctx: IMidwayKoaContext;
  @Inject()  userService: UserService;
  @CreateApiDoc()    .summary('get user')    .description('This a a open api for get user')    .param('user id', {      required: true,      example: 2,    })    .param('user name')    .respond(200, 'success', 'text', {      example: 'hello world',    })    .respond(500, 'throw error')    .build()  @Get('/:userId')  async getUser(@Param() userId: number, @Query() name?: string) {    return {      name: 'harry',      age: 18,    };  }}

四、其他#

midwayjs Swagger【增加返回数据的配置】https://www.yuque.com/kxuan/efuxvf/ute5ak