空氣越來越越糟糕，不得不上路了

在我還是個實習生的時候，我就困擾，這個世界上難道沒有寫完api文件之後，這個api文件自動幫你生成mock的測試資料，造福前後端的嗎？ 知道2年後，我看到了這個工具 blue print api ,這是官網 apiblueprint.org/documentati…

總體感受一遍

把你的文件寫成這個樣子，大體上是markdown

# Group  UserController

## 使用者登陸 [POST /users/login]
+ Request (application/json) 
    {
        "login": "tester",(string,required) -使用者名稱或者手機號 ,必填
        "password": "12346" (number,required) 密碼 ,必填
    }
+ Response 200 (application/json) 
    {
    "token": "fesrglkthtgrtgktlttthy" (string)使用者令牌
    }
+ Exception 
    ParameterException("Invalid user name or password.")  - 400, 使用者名稱/電話/電郵/密碼不對
    UserAccountException("User account suspended.")  - 401, 帳戶已被暫停
    UserAccountException("User account terminated.")  - 401, 帳戶已被刪除


複製程式碼

之後 自動生成html 檔案，長這個樣子

mock 測試資料功能，長這個樣子

開始操作

前提條件

• node 安裝
• vscode編輯器

node 安裝

下載安裝 : nodejs.org/dist/v10.13…

vscode編輯器

下載安裝：vscode.cdn.azure.cn/stable/5f24…

下載api文件倉庫 demo

gitee.com/lazytai/api…

gitlab.com/shaojunxiao…

##你還需要aglio， drakov aglio 用來生成 把markdown 生成 html drakov 用來生成 把markdown 生成 mock server

根據 aglio drakov express寫一個 服務系統

index.js

var hercule = require('hercule')
var utils = require('./utils/utils')
var fs = require('fs')
function getFileStr() {
    var _files = fs.readdirSync("./controllers");
    _files = utils.MyMap(_files, item => item = "./controllers/" + item)
    return _files
}

function getObjects() {
    var _files = fs.readdirSync("./objects");
    _files = utils.MyMap(_files, item => item = "./objects/" + item)
    _files = utils.mergeArray(["./z_dataStructures.apib"], _files)
    return _files
}
function getHeaderFile() {
    return ["./a_header.apib"]
}

function set_IndexApi() {
    var _files = utils.mergeArray(getHeaderFile(), getFileStr())
    _files = utils.mergeArray(_files, getObjects())
    var fileStr = ""
    for (var i = 0; i < _files.length; i++) {
        var file = _files[i]
        var _content = `:[${file.slice(2, file.length)}](${file})\n  \n`
        fileStr += _content
    }
    fs.writeFileSync("./_index.apib", fileStr)

}
function changeEvent() {
    set_IndexApi()
    hercule.transcludeFile("./_index.apib", (err, output) => {
        if (err) console.log(err)
        // console.log(output);
        fs.writeFileSync("./index.apib", output)
        var aglio = require('aglio')
        aglio.render(fs.readFileSync('./index.apib', 'utf-8'), {}, function (err, html, warnings) {
            // if (err) return console.log(err);
            // if (warnings) console.log(warnings);
            fs.writeFileSync("./views/index.html", html)
        });

    });
   
}


var chokidar = require('chokidar');
var watcher = chokidar.watch(['controllers', "objects"], {
    ignored: /(^|[\/\\])\../,
    persistent: true
});
watcher.on('change', path => {
    console.log(`File ${path} has been changed`)
    changeEvent()
})

changeEvent()
console.log("index.html create done");
var express = require('express')
var app = express()
app.use(express.static('./views'))
app.listen("9000")
console.log("html in  9000")


複製程式碼

根據步驟執行程式

cd ./專案根目錄

npm i

npm i drakov -g

//開啟html文件 開啟瀏覽器 localhost:9000
npm run start

//開啟mock server   開啟postman localhost:9002 測試
npm run mock
複製程式碼

編輯

在 ./api  資料夾下面新建新的 *.apib 檔案
根據apiblueprint 語法 編輯檔案，開啟localhost:9000檢視效果

複製程式碼

apiblueprint 語法

• Group 關鍵字

  • desc: 開始分組
  • demo: ## Group 工單

• 分組下面的二級條目

  • desc: 格式 二級條目名字 [GET,POST,DELETE,PUT /URL]
  • demo: ### 獲取工單狀況 [GET /production-orders/stat{?departmentId}]
  • note: 在url中新增 {?departmentId} 表明url帶的引數

• Parameters 關鍵字

  • desc: 描述 url的引數
  • demo: + id (number,required) 描述 ?id的型別和是否必要
  • note: 第一個引數:number,string,boolean,array,object 第二個引數可以使 required,optional

• Request 關鍵字

  • desc: 描述 前臺傳給後臺的引數
  • demo: + Request (application/json)
  • note: application/json 表示前臺json格式傳輸給後臺，也可以選擇 text/plain。Request需要搭配Attributes來描述具體的引數格式

• Attributes 關鍵字

  • desc: 描述 具體的引數格式
  • demo:

  + Request  (application/json)
     + Attributes
         + oldPassword(string,required)
         + newPassword(string,optional)  
  複製程式碼

• Response 關鍵字

  • desc: 描述 後臺傳給前臺的引數
  • demo:

  + Response 200 (application/json) 
      {
          "result": "ok"
      }
  
  or
  + Response 200 (application/json) 
      + Attributes (salesOrders)
  複製程式碼

  • note1: application/json 表示前臺json格式傳輸給前臺，也可以選擇 text/plain。Response可以搭配Attributes來描述具體的引數格式。或者直接寫一個json格式的物件，當做返回物件。200表示返回狀態,可以是401 402 403 404
  • note2: 如果使用Attributes描述，可以搭配 Data Structures 定義的model返回資料 比如salesOrders 就是在Data Structures 定義的

• Data Structures 關鍵字

  • desc: 描述 定義 model,所有的model都固定放在檔案 z_dataStructures.apib
  • demo:

  
  ## `address` (object)
  
  - `id`: `222` (number)
  - `surname`: `teststore` (string)
  - `givenName` (string)
  - `addressLine1` (string)
  - `addressLine2` (string)
  - `country` (string)
  - `state` (string)
  - `city` (string)
  - `district` (string)
  - `postcode` (string)
  - `mobile` (string)
  - `createTime`: `12434345` (number)
  - `userAddressStatusId`: `1` (number)
  - `userId`: `123` (number)
  
  
  複製程式碼

HAVE A GREAT JOURNEY END