利用apidoc自動生成model文件

天驅發表於2019-03-02
API

公司在之前進行存管對接後，對內部架構進行了細分，業務邏輯也比之前複雜了不少，由此資料庫文件的必要性顯得十分重要；組長參照了mysql在定義欄位時新增的comment欄位生成文件，在mongoose也使用了這一方式，然後通過讀取model.js生成符合apidoc的註釋，通過apidoc生成文件。

  • 先看效果：
    Screenshot from 2017-09-17 23-43-58.png
    Screenshot from 2017-09-17 23-43-58.png

說來慚愧，這任務本來是落在我身上，當時我根據apidoc的樣式模擬寫出html，但是顯示效果不好，組長就想到利用apidoc來生成文件，但是我拖拉了兩個週末後組長自己寫了demo，而後我只是做了樣式優化的部分

// 這是之前我寫得第一版
const TYPES = [String, Date, Boolean, Number]
const field = User.schema.obj
// console.log(field.type.name, field.comment)
let tbody = ``
// 定義空格符
const space = ` `
function renderTbody(data, index) {
  for (const attr in data) {
    index = index || 0
    // 如果是子屬性，則新增空格符
    let gap = ``
    for (let i = 0; i < index; i++) {
      gap += space
    }
    if (_.includes(TYPES, field[attr])) {
      tbody += `
      <tr>
        <td class="code">${gap}${attr}</td>
        <td>${typeof field[attr]()}</td>
        <td><p>${attr}</p></td>
      </tr>
    `
    } else if (attr.comment) {
      tbody += `
      <tr>
        <td class="code">${gap}${attr}</td>
        <td>${typeof field[attr].type()}</td>
        <td><p>${field[attr].comment}</p></td>
      </tr>
    `
    } else {
      renderTbody(field[attr], index + 1)
    }
  }
}
renderTbody(field)

const body = `
<table class="table">
    <thead>
        <tr>
            <th style="width: 30%">Field</th>
            <th style="width: 10%">Type</th>
            <th style="width: 40%">Description</th>
        </tr>
    </thead>
    <tbody>
        ${tbody}
    </tbody>
</table>
`
let html = `<!DOCTYPE html>
<html>
  <head id="head">
    <meta charset="UTF-8">
    <meta name="format-detection" content="telephone=no">
    <meta name="Description" content="modelDoc">
    <title>modelDoc</title>
    <link rel="stylesheet" type="text/css" href="./modelDoc.css">
  </head>
  <body>
    <h3>${User.schema.name}</h3>
    ${body}
  </body>
</html>`
console.log(`生成頁面...`)
fs.writeFileSync(path.resolve(__dirname, `../../assets/modelDoc/index.html`), html)
process.exit(0)複製程式碼

以下是apidoc的版本

  • 先來看看model的定義 
    attributes: {
  uid: { type: String, required: true, index: true, comment: `使用者id` },
  amount: { type: Number, required: true, comment: `金額` },
  oType: {
    type: Number,
    required: true,
    enum: Object.values(Constant.ORDER_TYPE),
    comment: `訂單型別`
  },
  channel: { type: String, required: true, default: Constant.CHANNEL.SYSTEM, comment: `訂單來源渠道` },
  os: { type: String, required: true, default: Constant.CLIENT.SYSTEM, comment: `發起終端` },
  status: { type: Number, required: true, comment: `狀態` },
  time: { type: Number, required: true, comment: `訂單建立時間` },
  doneTime: { type: Number, comment: `訂單完成時間` },
  expireTime: { type: Number, comment: `訂單失效時間` },
  // 充值提現訂單有
  bank: { type: String, comment: `銀行編碼` },
  bankcard: { type: String, comment: `銀行卡號` },
  // 購買還款訂單有
  product: { type: Object, comment: `產品` },
  asset_id: { type: String, comment: `資產id` },
  extend: {
    type: Object
    // 統計所有用到extend的地方，都加上
    // isLazy: {type: Boolean, comment: `是否自動投資`}
  },
  message: { type: String, comment: `失敗原因` }
}複製程式碼
  • model層使用了指令碼讀取檔案
const fs = require(`fs`);
const path = require(`path`);

const models = fs.readdirSync(path.resolve(__dirname, `./`));
let ret = {};
for (const model of models) {
  ret[model.slice(0, model.indexOf(`.js`))] = require(`./${model}`)
}
module.exports = ret;複製程式碼

因此在讀取model時只需要const models = require(`../../app/model/`)

  • 先定義apidoc的name和group，然後通過generateFieldDoc函式生成相應的註釋，最後將生成的註釋寫入指定的檔案內 
    for (let i in models) {
let model = models[i]
const schema = model.schema.obj
doc += `
/**
* @api {POST} /${model.modelName} ${model.modelName}
* @apiName ${model.modelName}
* @apiGroup model
`
for (let attr in schema) {
  doc += generateFieldDoc(attr, schema[attr])
}
doc += ` */
`
}
fs.writeFileSync(path.resolve(__dirname, `../../app/model/modelDoc.js`), doc)
process.exit(0)複製程式碼
function generateFieldDoc (key, value) {
  let prefix = ` * @apiParam`
  let defaultStr = ``
  let enumStr = ``
  // 這裡呼叫lodash的isFunction，相容type: String這種寫法
  if (_.isFunction(value)) {
    return `${prefix} {${value.name}} ${key}
`
  }
  if (_.isObject(value) && value.type) {
    let description = value.comment || ``
    // apidoc沒有索引標誌，所以只能寫在description
    if (value.index) {
      description += ` (加索引)`
    }
    // 只能規定的值
    if (value.enum) {
      // 區分number和string
      if (value.type === Number){
        enumStr += `=${value.enum.join(`,`)}`
      } else if (value.type === String){
        enumStr += `="${value.enum.join(`","`)}"`
      }
    }
    // 是否有預設值
    if (value.default) {
      defaultStr += value.type === String ? `="${value.default}"` : `=${value.default}`
    }
    // 是否必填
    if (!value.required) {
      if (value.enum) {
        key = `[${key}`
        enumStr = `${enumStr}]`
      } else {
        key = `[${key}]`
      }
    }
    return `${prefix} {${value.type.name}${enumStr}} ${key}${defaultStr} ${description}
`
  }
  const type = _.isArray(value) ? `Array` : `Object`
  let ret = `${prefix} {${type}} ${key}
`
  // 若是陣列，將遞迴執行generateFieldDoc
  for (let attr in value) {
    ret += generateFieldDoc(`${key}.${attr}`, value[attr])
  }
  return ret
}複製程式碼

總結

總得來說，藉助apidoc生成model文件，是可以滿足檢視的需求，而且顯示上可以與介面文件存放在同一位置統一檢視，不過在顯示效果上可以缺失了索引等屬性。

相關文章