中文版本 | English Version
基于 swagger-decorator 的自动实体类构建与 Swagger 接口文档生成是笔者对于开源项目 swagger-decorator 的描述,对于不反感使用注解的项目中利用 swagger-decorator 添加合适的实体类或者接口类注解,从而实现支持嵌套地实体类校验与生成、Sequelize 等 ORM 模型生成、基于 Swagger 的接口文档生成等等功能。如果有对 JavaScript 语法使用尚存不明的可以参考 JavaScript 学习与实践资料索引或者现代 JavaScript 开发:语法基础与实践技巧系列文章。
swagger-decorator: 一处注解,多处使用
swagger-decorator 的初衷是为了简化 JavaScript 应用开发,笔者在编写 JavaScript 应用(Web 前端 & Node.js)时发现我们经常需要重复地创建实体类、添加注释或者进行类型校验,swagger-decorator 希望能够让开发者一处注解、多处使用。需要强调的是,在笔者多年的 Java 应用开发中也感受到,过多过度的注解反而会大大削弱代码的可读性,因此笔者也建议应该在合适的时候舒心地使用 swagger-decorator,而不是本末倒置,一味地追求注解覆盖率。swagger-decorator 已经可以用于实体类生成与校验、Sequelize ORM 实体类生成、面向 Koa 的路由注解与 Swagger 文档自动生成。我们可以使用 yarn 或者 npm 安装 swagger-decorator 依赖,需要注意的是,因为我们在开发中还会用到注解语法,因此还需要添加 babel-plugin-transform-decorators-legacy 插件以进行语法兼容转化。
# 使用 npm 安装依赖 $ npm install swagger-decorator -S $ npm install babel-plugin-transform-decorators-legacy -D # 使用 yarn 安装依赖 $ yarn add swagger-decorator $ yarn add babel-plugin-transform-decorators-legacy -D # 导入需要的工具函数 import from "swagger-decorator";
实体类注解
swagger-decorator 的核心 API 即是对于实体类的注解,该注解不会改变实体类的任何属性表现,只是会将注解限定的属性特性记录在内置的 innerEntityObject 单例中以供后用。属性注解 entityProperty 的方法说明如下:
/** * Description 创建某个属性的描述 * @param type 基础类型 self - 表示为自身 * @param description 描述 * @param required 是否为必要参数 * @param defaultValue 默认值 * @param pattern * @param primaryKey 是否为主键 * @returns */ {}
简单的用户实体类注解如下,这里的数据类型 type 支持 Swagger 默认的字符格式的类型描述,也支持直接使用 JavaScript 类名或者 JavaScript 数组。
// @flow ;;/** * Description 用户实体类 */ // 编号 @ id: string = 0; // 姓名 @ name: string = "name"; // 邮箱 @ email: string = "email"; // 属性 @ property: UserProperty = ; // 朋友列表 @ friends: number;
Swagger 内置数据类型定义:
实例生成与校验
实体类定义完毕之后,我们首先可以使用 instantiate 函数为实体类生成实例;不同于直接使用 new 关键字创建,instantiate 能够根据指定属性的数据类型或者格式进行校验,同时能够迭代生成嵌套地子对象。
/** * Description 从实体类中生成对象,并且进行数据校验;注意,这里会进行递归生成,即对实体类对象同样进行生成 * @param EntityClass 实体类 * @param data 数据对象 * @param ignore 是否忽略校验 * @param strict 是否忽略非预定义类属性 * @throws 当校验失败,会抛出异常 */: Object {}
这里为了方便描述使用 Jest 测试用例说明不同的使用场景:
; ;
Sequelize 模型生成
Sequelize 是 Node.js 应用中常用的 ORM 框架,swagger-decorator 提供了 generateSequelizeModel 函数以方便从实体类中利用现有的信息生成 Sequelize 对象模型;generateSequelizeModel 的第一个参数输入实体类,第二个参数输入需要覆写的模型属性,第三个参数设置额外属性,譬如是否需要将驼峰命名转化为下划线命名等等。
const originUserSequelizeModel = ; const UserSequelizeModel = sequelize; UserSequelizeModel;
从 Flow 类型声明中自动生成注解
笔者习惯使用 Flow 作为 JavaScript 的静态类型检测工具,因此笔者添加了 flowToDecorator 函数以自动地从 Flow 声明的类文件中提取出类型信息;内部原理参考现代 JavaScript 开发:语法基础与实践技巧 一书中的 JavaScript 语法树与代码转化章节。该函数的使用方式为:
// @flow
import { flowToDecorator } from '../../../../src/transform/entity/flow/flow';
test('测试从 Flow 中提取出数据类型并且转化为 Swagger 接口类', () => {
flowToDecorator('./TestEntity.js', './TestEntity.transformed.js').then(
codeStr => {
console.log(codeStr);
},
err => {
console.error(err);
}
);
});
这里对应的 TestEntity 为:
// @flow
import AnotherEntity from "./AnotherEntity";
class Entity {
// Comment
stringProperty: string = 0;
classProperty: Entity = null;
rawProperty;
@entityProperty({
type: "string",
description: "this is property description",
required: true
})
decoratedProperty;
}
转化后的实体类为:
// @flow
import { entityProperty } from 'swagger-decorator';
import AnotherEntity from './AnotherEntity';
class Entity {
// Comment
@entityProperty({
type: 'string',
required: false,
description: 'Comment'
})
stringProperty: string = 0;
@entityProperty({
type: Entity,
required: false
})
classProperty: Entity = null;
@entityProperty({
type: 'string',
required: false
})
rawProperty;
@entityProperty({
type: 'string',
description: 'this is property description',
required: true
})
decoratedProperty;
}
接口注解与 Swagger 文档生成
对于 Swagger 文档规范可以参考 OpenAPI Specification ,而对于 swagger-decorator 的实际使用可以参考本项目的使用示例或者 基于 Koa2 的 Node.js 应用模板 。
封装路由对象
; ... const Router = ; const router = ; ; // define default routerouter; // use scan to auto add method in classrouter;
定义接口类
@ @ static async : User ctxbody = ; @ @ static async : User ctxbody = ; @ @ static async : number ctxbody = statusCode: 200 ;
在 UserController 中是负责具体的业务实现,为了避免过多的注解文档对于代码可读性的干扰,笔者建议是将除了路径与描述之外的信息放置到父类中声明;swagger-decorator 会自动从某个接口类的直接父类中提取出同名方法的描述文档。
@ static async : User {} @ @ @ static async : User {} @ @ static async : number {}
运行应用
- run your application and open swagger docs (PS. swagger-decorator contains Swagger UI):
/swagger
/swagger/api.json
About
RoadMap
- 引入 swagger-to-slate 以支持 Slate 文档
- 修复实体类自动生成中可能存在的错误
- 复合类型推导
- 接口数据自动校验