markdown 寫 api 系統

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

在我仍是個實習生的時候，我就困擾，這個世界上難道沒有寫完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