JavaScript 中基于 swagger-decorator 的自動實體類構(gòu)建與 Swagger 接口文檔生成是筆者對于開源項目 swagger-decorator 的描述，對于不反感使用注解的項目中利用 swagger-decorator 添加合適的實體類或者接口類注解，從而實現(xiàn)支持嵌套地實體類校驗與生成、Sequelize 等 ORM 模型生成、基于 Swagger 的接口文檔生成等等功能。如果有對 JavaScript 語法使用尚存不明的可以參考 JavaScript 學習與實踐資料索引或者現(xiàn)代 JavaScript 開發(fā)：語法基礎(chǔ)與實踐技巧系列文章。

swagger-decorator: 一處注解，多處使用

swagger-decorator 的初衷是為了簡化 JavaScript 應(yīng)用開發(fā)，筆者在編寫 JavaScript 應(yīng)用(Web 前端 & Node.js)時發(fā)現(xiàn)我們經(jīng)常需要重復(fù)地創(chuàng)建實體類、添加注釋或者進行類型校驗，swagger-decorator 希望能夠讓開發(fā)者一處注解、多處使用。需要強調(diào)的是，在筆者多年的 Java 應(yīng)用開發(fā)中也感受到，過多過度的注解反而會大大削弱代碼的可讀性，因此筆者也建議應(yīng)該在合適的時候舒心地使用 swagger-decorator，而不是本末倒置，一味地追求注解覆蓋率。swagger-decorator 已經(jīng)可以用于實體類生成與校驗、Sequelize ORM 實體類生成、面向 Koa 的路由注解與 Swagger 文檔自動生成。我們可以使用 yarn 或者 npm 安裝 swagger-decorator 依賴，需要注意的是，因為我們在開發(fā)中還會用到注解語法，因此還需要添加 babel-plugin-transform-decorators-legacy 插件以進行語法兼容轉(zhuǎn)化。

# 使用 npm 安裝依賴 
 
$ npm install swagger-decorator -S 
 
$ 
 
# 使用 yarn 安裝依賴 
 
$ yarn add swagger-decorator 
 
$ yarn add babel-plugin-transform-decorators-legacy -D 
 
# 導入需要的工具函數(shù) 
import {  
    wrappingKoaRouter, 
    entityProperty, 
    ... 
} from "swagger-decorator"; 

實體類注解

swagger-decorator 的核心 API 即是對于實體類的注解，該注解不會改變實體類的任何屬性表現(xiàn)，只是會將注解限定的屬性特性記錄在內(nèi)置的 innerEntityObject 單例中以供后用。屬性注解 entityProperty 的方法說明如下：

/** 
 * Description 創(chuàng)建某個屬性的描述 
 * @param type 基礎(chǔ)類型 self - 表示為自身 
 * @param description 描述 
 * @param required 是否為必要參數(shù) 
 * @param defaultValue 默認值 
 * @param pattern 
 * @param primaryKey 是否為主鍵 
 * @returns {Function} 
 */ 
export function entityProperty({ 
  // 生成接口文檔需要的參數(shù) 
  type = "string", 
  description = "", 
  required = false, 
  defaultValue = undefined, 
 
  // 進行校驗所需要的參數(shù) 
  pattern = undefined, 
 
  // 進行數(shù)據(jù)庫連接需要的參數(shù) 
  primaryKey = false 
}) {} 

簡單的用戶實體類注解如下，這里的數(shù)據(jù)類型 type 支持 Swagger 默認的字符格式的類型描述，也支持直接使用 JavaScript 類名或者 JavaScript 數(shù)組。

// @flow 
 
import { entityProperty } from "../../src/entity/decorator"; 
import UserProperty from "./UserProperty"; 
/** 
 * Description 用戶實體類 
 */ 
export default class User { 
  // 編號 
  @entityProperty({ 
    type: "integer", 
    description: "user id, auto-generated", 
    required: true 
  }) 
  id: string = 0; 
 
  // 姓名 
  @entityProperty({ 
    type: "string", 
    description: "user name, 3~12 characters", 
    required: false 
  }) 
  name: string = "name"; 
 
  // 郵箱 
  @entityProperty({ 
    type: "string", 
    description: "user email", 
    pattern: "email", 
    required: false 
  }) 
  email: string = "email"; 
 
  // 屬性 
  @entityProperty({ 
    type: UserProperty, 
    description: "user property", 
    required: false 
  }) 
  property: UserProperty = new UserProperty(); 
} 
 
export default class UserProperty { 
  // 朋友列表 
  @entityProperty({ 
    type: ["number"], 
    description: "user friends, which is user ids", 
    required: false 
  }) 
  friends: [number]; 
} 

Swagger 內(nèi)置數(shù)據(jù)類型定義：

Common NametypeformatCommentsintegerintegerint32signed 32 bitslongintegerint64signed 64 bitsfloatnumberfloatdoublenumberdoublestringstringbytestringbytebase64 encoded charactersbinarystringbinaryany sequence of octetsbooleanbooleandatestringdateAs defined by full-date - RFC3339dateTimestringdate-timeAs defined by date-time - RFC3339passwordstringpasswordUsed to hint UIs the input needs to be obscured.

實例生成與校驗

實體類定義完畢之后，我們首先可以使用 instantiate 函數(shù)為實體類生成實例;不同于直接使用 new 關(guān)鍵字創(chuàng)建，instantiate 能夠根據(jù)指定屬性的數(shù)據(jù)類型或者格式進行校驗，同時能夠迭代生成嵌套地子對象。

/** 
 * Description 從實體類中生成對象，并且進行數(shù)據(jù)校驗；注意，這里會進行遞歸生成，即對實體類對象同樣進行生成 
 * @param EntityClass 實體類 
 * @param data 數(shù)據(jù)對象 
 * @param ignore 是否忽略校驗 
 * @param strict 是否忽略非預(yù)定義類屬性 
 * @throws 當校驗失敗，會拋出異常 
 */ 
export function instantiate( 
  EntityClass: Function, 
  data: { 
    [string]: any 
  }, 
  { ignore = false, strict = true }: { ignore: boolean, strict: boolean } = {} 
): Object {} 

這里為了方便描述使用 Jest 測試用例說明不同的使用場景：

/** 
 * Description 從實體類中生成對象，并且進行數(shù)據(jù)校驗；注意，這里會進行遞歸生成，即對實體類對象同樣進行生成 
 * @param EntityClass 實體類 
 * @param data 數(shù)據(jù)對象 
 * @param ignore 是否忽略校驗 
 * @param strict 是否忽略非預(yù)定義類屬性 
 * @throws 當校驗失敗，會拋出異常 
 */ 
export function instantiate( 
  EntityClass: Function, 
  data: { 
    [string]: any 
  }, 
  { ignore = false, strict = true }: { ignore: boolean, strict: boolean } = {} 
): Object {} 
這里為了方便描述使用 Jest 測試用例說明不同的使用場景： 
 
describe("測試實體類實例化函數(shù)", () => { 
  test("測試 User 類實例化校驗", () => { 
    expect(() => { 
      instantiate(User, { 
        name: "name" 
      }).toThrowError(/validate fail!/); 
    }); 
 
    let user = instantiate(User, { 
      id: 0, 
      name: "name", 
      email: "a@q.com" 
    }); 
 
    // 判斷是否為 User 實例 
    expect(user).toBeInstanceOf(User); 
  }); 
 
  test("測試 ignore 參數(shù)可以允許忽略校驗", () => { 
    instantiate( 
      User, 
      { 
        name: "name" 
      }, 
      { 
        ignore: true 
      } 
    ); 
  }); 
 
  test("測試 strict 參數(shù)可以控制是否忽略額外參數(shù)", () => { 
    let user = instantiate( 
      User, 
      { 
        name: "name", 
        external: "external" 
      }, 
      { 
        ignore: true, 
        strict: true 
      } 
    ); 
 
    expect(user).not.toHaveProperty("external", "external"); 
 
    user = instantiate( 
      User, 
      { 
        name: "name", 
        external: "external" 
      }, 
      { 
        ignore: true, 
        strict: false 
      } 
    ); 
 
    expect(user).toHaveProperty("external", "external"); 
  }); 
}); 
 
describe("測試嵌套實例生成", () => { 
  test("測試可以遞歸生成嵌套實體類", () => { 
    let user = instantiate(User, { 
      id: 0, 
      property: { 
        friends: [0] 
      } 
    }); 
 
    expect(user.property).toBeInstanceOf(UserProperty); 
  }); 
}); 

Sequelize 模型生成

Sequelize 是 Node.js 應(yīng)用中常用的 ORM 框架，swagger-decorator 提供了 generateSequelizeModel 函數(shù)以方便從實體類中利用現(xiàn)有的信息生成 Sequelize 對象模型;generateSequelizeModel 的第一個參數(shù)輸入實體類，第二個參數(shù)輸入需要覆寫的模型屬性，第三個參數(shù)設(shè)置額外屬性，譬如是否需要將駝峰命名轉(zhuǎn)化為下劃線命名等等。

const originUserSequelizeModel = generateSequelizeModel( 
  User, 
  { 
    _id: { 
      primaryKey: true 
    } 
  }, 
  { 
    mappingCamelCaseToUnderScore: true 
  } 
); 
 
const UserSequelizeModel = sequelize.define( 
  "b_user", 
  originUserSequelizeModel, 
  { 
    timestamps: false, 
    underscored: true, 
    freezeTableName: true 
  } 
); 
 
UserSequelizeModel.findAll({ 
  attributes: { exclude: [] } 
}).then(users => { 
  console.log(users); 
}); 

從 Flow 類型聲明中自動生成注解

筆者習慣使用 Flow 作為 JavaScript 的靜態(tài)類型檢測工具，因此筆者添加了 flowToDecorator 函數(shù)以自動地從 Flow 聲明的類文件中提取出類型信息;內(nèi)部原理參考現(xiàn)代 JavaScript 開發(fā)：語法基礎(chǔ)與實踐技巧 一書中的 JavaScript 語法樹與代碼轉(zhuǎn)化章節(jié)。該函數(shù)的使用方式為：

// @flow 
 
import { flowToDecorator } from '../../../../src/transform/entity/flow/flow'; 
 
test('測試從 Flow 中提取出數(shù)據(jù)類型并且轉(zhuǎn)化為 Swagger 接口類', () => { 
  flowToDecorator('./TestEntity.js', './TestEntity.transformed.js').then( 
    codeStr => { 
      console.log(codeStr); 
    }, 
    err => { 
      console.error(err); 
    } 
  ); 
}); 

這里對應(yīng)的 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; 
} 

轉(zhuǎn)化后的實體類為：

// @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 文檔規(guī)范可以參考 OpenAPI Specification ，而對于 swagger-decorator 的實際使用可以參考本項目的使用示例或者 基于 Koa2 的 Node.js 應(yīng)用模板 。

封裝路由對象

import { wrappingKoaRouter } from "swagger-decorator"; 
 
... 
 
const Router = require("koa-router"); 
 
const router = new Router(); 
 
wrappingKoaRouter(router, "localhost:8080", "/api", { 
  title: "Node Server Boilerplate", 
  version: "0.0.1", 
  description: "Koa2, koa-router,Webpack" 
}); 
 
// define default route 
router.get("/", async function(ctx, next) { 
  ctx.body = { msg: "Node Server Boilerplate" }; 
}); 
 
// use scan to auto add method in class 
router.scan(UserController); 

定義接口類

export default class UserController extends UserControllerDoc { 
  @apiRequestMapping("get", "/users") 
  @apiDescription("get all users list") 
  static async getUsers(ctx, next): [User] { 
    ctx.body = [new User()]; 
  } 
 
  @apiRequestMapping("get", "/user/:id") 
  @apiDescription("get user object by id, only access self or friends") 
  static async getUserByID(ctx, next): User { 
    ctx.body = new User(); 
  } 
 
  @apiRequestMapping("post", "/user") 
  @apiDescription("create new user") 
  static async postUser(): number { 
    ctx.body = { 
      statusCode: 200 
    }; 
  } 
} 

在 UserController 中是負責具體的業(yè)務(wù)實現(xiàn)，為了避免過多的注解文檔對于代碼可讀性的干擾，筆者建議是將除了路徑與描述之外的信息放置到父類中聲明;swagger-decorator 會自動從某個接口類的直接父類中提取出同名方法的描述文檔。

export default class UserControllerDoc { 
  @apiResponse(200, "get users successfully", [User]) 
  static async getUsers(ctx, next): [User] {} 
 
  @pathParameter({ 
    name: "id", 
    description: "user id", 
    type: "integer", 
    defaultValue: 1 
  }) 
  @queryParameter({ 
    name: "tags", 
    description: "user tags, for filtering users", 
    required: false, 
    type: "array", 
    items: ["string"] 
  }) 
  @apiResponse(200, "get user successfully", User) 
  static async getUserByID(ctx, next): User {} 
 
  @bodyParameter({ 
    name: "user", 
    description: "the new user object, must include user name", 
    required: true, 
    schema: User 
  }) 
  @apiResponse(200, "create new user successfully", { 
    statusCode: 200 
  }) 
  static async postUser(): number {} 
} 

運行應(yīng)用

run your application and open swagger docs (PS. swagger-decorator contains Swagger UI): 
/swagger 

/swagger/api.json 

 【本文是51CTO專欄作者“張梓雄 ”的原創(chuàng)文章，如需轉(zhuǎn)載請通過51CTO與作者聯(lián)系】

戳這里，看該作者更多好文