摘要：注解方式為應(yīng)用動(dòng)態(tài)生成文檔目前我司服務(wù)端應(yīng)用程序框架主要采用了與，而因?yàn)榻衲暧泻芏嗟恼{(diào)研階段的產(chǎn)品線發(fā)布，持續(xù)部署接口文檔以及線上質(zhì)量監(jiān)控這三個(gè)問(wèn)題愈發(fā)突出。

swagger-decorator：注解方式為 Koa2 應(yīng)用自動(dòng)生成 Swagger 文檔 從屬于筆者的服務(wù)端應(yīng)用程序開發(fā)與系統(tǒng)架構(gòu)，記述了如何在以 Koa2 與 koa-router 開發(fā)服務(wù)端應(yīng)用時(shí)，通過(guò)自定義 swagger-decorator 庫(kù)來(lái)實(shí)現(xiàn)類 Spring-Boot 中注解方式動(dòng)態(tài)生成 Swagger 標(biāo)準(zhǔn)的接口文檔。

目前我司服務(wù)端應(yīng)用程序框架主要采用了 Java Spring 與 Node.js，而因?yàn)榻衲暧泻芏嗟恼{(diào)研階段的產(chǎn)品線 Demo 發(fā)布，持續(xù)部署、接口文檔以及線上質(zhì)量監(jiān)控這三個(gè)問(wèn)題愈發(fā)突出。本文則主要針對(duì)接口文檔的實(shí)時(shí)發(fā)布進(jìn)行一些探討；在前后端分離的今天，即使是由單人縱向負(fù)責(zé)某個(gè)業(yè)務(wù)流，也需要將前后端交互的接口規(guī)范清晰地定義并且發(fā)布，以保證項(xiàng)目的透明性與可維護(hù)性。理想的開發(fā)流程中，應(yīng)當(dāng)在產(chǎn)品設(shè)計(jì)階段確定好關(guān)鍵字段命名、數(shù)據(jù)庫(kù)表設(shè)計(jì)以及接口文檔；不過(guò)實(shí)際操作中往往因?yàn)闃I(yè)務(wù)的多變性以及人手的缺失，使得接口的定義并不能總是實(shí)時(shí)地在項(xiàng)目成員之間達(dá)成一致。如果要讓開發(fā)人員在更改接口的同時(shí)花費(fèi)額外精力維護(hù)一份開發(fā)文檔，可能對(duì)于我司這樣的小公司而言存在著很大的代價(jià)與風(fēng)險(xiǎn)。軟件開發(fā)中存在著所謂 Single Source of Truth 的原則，我們也需要盡量避免文檔與實(shí)際實(shí)現(xiàn)的不一致造成的團(tuán)隊(duì)內(nèi)矛盾以及無(wú)用的付出。綜上所述，我們希望能夠在編寫后臺(tái)代碼、添加注釋的同時(shí)，能夠自動(dòng)地生成接口文檔；筆者比較熟悉 Spring 中以注解方式添加 Swagger 文檔的模式，不過(guò) Java 庫(kù)的抽象程度一般較高，用起來(lái)也不怎么順手。筆者在編寫我司 node-server-boilerplate 根據(jù)自己的想法設(shè)計(jì)了 swagger-decorator。此外，項(xiàng)目中使用 Flow 進(jìn)行靜態(tài)類型檢測(cè)，并且遵循我司內(nèi)部的 JavaScript 編程樣式指南。

我們可以使用 npm 或者 yarn 安裝 swagger-decorator，需要注意的是，因?yàn)槭褂昧俗⒔猓虼私ㄗh是配置 Webpack 與 Babel，不熟悉的同學(xué)可以直接參考 node-server-boilerplate ：

$ yarn add swagger-decorator

# 依賴于 Babel 的 transform-decorators-legacy 轉(zhuǎn)換插件來(lái)使用 Decorator
$ yarn add transform-decorators-legacy -D

安裝完畢之后，我們需要對(duì)項(xiàng)目中使用的路由進(jìn)行封裝。目前筆者只是針對(duì) koa-router 中的路由對(duì)象進(jìn)行封裝，未來(lái)若有必要可以針對(duì)其他框架的路由解決方案進(jìn)行封裝。我們首先需要做的就是在路由定義之前使用 wrappingKoaRouter 函數(shù)修飾 router 對(duì)象：

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"
});

//定義默認(rèn)的根路由
router.get("/", async function(ctx, next) {
  ctx.body = { msg: "Node Server Boilerplate" };
});

//定義用戶處理路由
router.scan(UserController);

該函數(shù)的參數(shù)說(shuō)明如下，對(duì)于 info 的結(jié)構(gòu)參考這里：

/**
 * Description 將 router 對(duì)象的方法進(jìn)行封裝
 * @param router 路由對(duì)象
 * @param host API 域名
 * @param basePath API 基本路徑
 * @param info 其他的 Swagger 基本信息
 */
export function wrappingKoaRouter(
  router: Object,
  host: string = "localhost",
  basePath: string = "",
  info: Object = {}
) {}

值得一提的是，在封裝 router 時(shí)，筆者自定義了 scan 方法，其能夠根據(jù)自動(dòng)遍歷目標(biāo)類中的自定義方法，有點(diǎn)類似于 Java 中的 ComponentScan：

/**
* Description 掃描某個(gè)類中的所有靜態(tài)方法，按照其注解將其添加到
* @param staticClass
*/
router.scan = function(staticClass: Function) {
    let methods = Object.getOwnPropertyNames(staticClass);
    
    // 移除前三個(gè)屬性 constructor、name
    methods.shift();
    methods.shift();
    methods.shift();
    
    for (let method of methods) {
      router.all(staticClass[method]);
    }
};

準(zhǔn)備工作完成之后，我們即可以開始定義具體的接口控制器；筆者不喜歡過(guò)多的封裝，因此這里選用了類的靜態(tài)方法來(lái)定義具體的接口函數(shù)，整個(gè) Controller 也只是樸素函數(shù)。下面筆者列舉了常見的獲取全部用戶列表、根據(jù)用戶編號(hào)獲取用戶詳情、創(chuàng)建新用戶這幾個(gè)接口的文檔注釋方式：

import {
  apiDescription,
  apiRequestMapping,
  apiResponse,
  bodyParameter,
  pathParameter,
  queryParameter
} from "swagger-decorator";
import User from "../entity/User";

/**
 * Description 用戶相關(guān)控制器
 */
export default class UserController {
  @apiRequestMapping("get", "/users")
  @apiDescription("get all users list")
  @apiResponse(200, "get users successfully", [User])
  static async getUsers(ctx, next): [User] {
    ...
  }

  @apiRequestMapping("get", "/user/:id")
  @apiDescription("get user object by id, only access self or friends")
  @pathParameter({
    name: "id",
    description: "user id",
    type: "integer"
  })
  @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 {
    ...
  }

  @apiRequestMapping("post", "/user")
  @apiDescription("create new user")
  @bodyParameter({
    name: "user",
    description: "the new user object, must include user name",
    required: true,
    schema: User
  })
  @apiResponse(200, "create new user successfully", {
    status_code: "200"
  })
  static async postUser(): number {
    ...
  }
}

在對(duì)接口注解的時(shí)候，我們需要用實(shí)體類指明返回值或者請(qǐng)求體中包含的參數(shù)信息，因此我們也需要使用 swagger-decorator 提供的 entityProperty 注解來(lái)為實(shí)體類添加描述。值得一提的是，這里我們支持直接將 Object 作為描述對(duì)象的返回值，算是避免了 Java 中的一大痛點(diǎn)。

// @flow

import { entityProperty } from "swagger-decorator";
/**
 * Description 用戶實(shí)體類
 */
export default class User {
  // 編號(hào)
  @entityProperty({
    type: "integer",
    description: "user id, auto-generated",
    required: false
  })
  id: string = 0;

  // 姓名
  @entityProperty({
    type: "string",
    description: "user name, 3~12 characters",
    required: true
  })
  name: string = "name";

  // 朋友列表
  friends: [number] = [1];

  // 屬性
  properties: {
    address: string
  } = {
    address: "address"
  };
}

對(duì)于沒(méi)有添加注解的屬性，swagger-decorator 會(huì)自動(dòng)根據(jù)其默認(rèn)值來(lái)推測(cè)類型。然后我們就可以正常地啟動(dòng)應(yīng)用，swagger-decorator 已經(jīng)自動(dòng)地為 router 對(duì)象添加了兩個(gè)路由，其中 /swagger 指向了 Swagger UI：

而 /swagger/api.json 指向了 Swagger 生成的 JSON 文檔：

歡迎有興趣的朋友提出 ISSUE、指導(dǎo)意見或者希望納入的特性。