使用aglio书写API文档

最近开始新项目,统筹前端/App/后台的开发设计。在定义后台API的时候,原先打算使用 doxygen 采用注释的方式。后来找到了aglio,由于平时经常使用 markdown 格式书写文档,因此决定使用aglio。 使用 npm 安装 aglio,安装后基本的命令如下:

aglio -i /input.apib -o /output.html

后缀apib即是符合 API Blueprint 格式的文件。需要说明的是, aglio 解析 API Blueprint 格式将其转化成html,生成的html可以部署到服务器上进行mock测试。因此,在书写的时候,不仅仅要遵守语法规则,还要遵守API本身的语义。

下面是个简单的例子:

FORMAT: 1A
HOST: https://api.example.com
# Server API Definitions
## Introduction
定义App与后台通信的API种类和格式
# Group XXX API
## testxxx [/testxxx]
### 简单的说明 [POST]  
+ Request (application/json)
        {
            "number": "MSS00001",
            "volum": 3201.98,
            "address": "中国xx省无xx市xx区xx街道 东200米",
            "uploadTime": "2017-10-30 14:28:09"
        }
+ Response 200 (application/json)
        {
            "statuCode": 200,
            "result": "success"
        }

需要注意的是 Response后要空8个空格或是2个tab,如果少了空格,aglio会有响应的错误输出。