markdown 寫 api 系統

莫欺少年窮發表於2018-11-30
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 檔案，長這個樣子

image.png

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

image.png

開始操作

前提條件

  • 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， drakovaglio 用來生成 把markdown 生成 htmldrakov 用來生成 把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 inpm i drakov -g//開啟html文件 開啟瀏覽器 localhost:9000npm 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 JOURNEYEND

來源：https://juejin.im/post/5c00b4e8f265da613b6f8096

相關文章