跳到主要内容
版本:2.0.0

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@1 --save
npm 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 描述请求

通过 summarydescription 方法,我们可以对整个接口进行描述。

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 方法可以描述接口的参数,按顺序描述参数。如果有多个参数,则可以调用多次。以我们的示例为例,有两个参数, userIdname

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,
};
}
}

更多配置

可以修改默认的 Swagger 版本,描述等。这些配置可以在用户配置,比如 src/config/config.default.ts  中配置。

export const swagger = {
title: 'midway-swagger',
description: 'swagger-ui for midway api',
version: '1.0.0',
termsOfService: '',
contact: {
name: 'API Support',
url: 'http://www.example.com/support',
email: 'support@example.com',
},
license: {
name: 'Apache 2.0',
url: 'https://www.apache.org/licenses/LICENSE-2.0.html',
},
};

四、其他

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