使用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会有响应的错误输出。

Comments

Categories

Tags