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