什么是 aglio
Aglio是一个自动生成API文档的工具。利用Markdown格式编写API蓝本定义，然后生成一个漂亮的HTML文档，还可以与其他开发者共享。
安装
Aglio可以通过npm进行安装：
npm install -g aglio
使用
用法很简单：
aglio -i input_file.apib -o output_file.html
其中，-i是输入文件的路径，-o是输出文件的路径。
Markdown语法
Aglio使用除少数例外的Markdown语法，但是增加了一些自定义语法来帮助描述API蓝本。
主要语法
Group
# Group 标题
定义一个API组
Resource
## 资源名称 [/uri]
定义API资源，其中uri是可选的。
Action
### Action名称 [METHOD]
定义API动作，METHOD是HTTP方法名：GET，POST，PUT，DELETE等。
Parameter
+ 参数名 (类型) - 描述 (默认值)
定义一个输入参数，其中类型和默认值可选。
RequestBody
+ RequestBody
定义请求主体
Response
+ 响应码 (类型) - 描述
定义API响应状态和描述
Attributes
+ 属性 (类型, 选项) - 描述 (默认值)
定义一个属性，其中类型和默认值可选
高级语法
Aglio还支持其他很多自定义语法，例如：
- Variables
- MSON structures
- JSON structures
- Custom actions
- Custom Views
示例
以下是一个简单的API蓝本：
-- -------------------- ---- -------
------- --
- -- ---
---- -- - ----------- -- -- ----
-- --------
---- -- - ------ --- ---- ------- - --------
--- --- ------- -----
---- - ------- ---- --- -------
- -------- --- ------------
- ----------
- -------- --- -------
- ----- --- ------ ----
- ----- -----
----- ---- --- ---- --------- -- ---------------
-- ------
--- ------ ---- ------
------- - --- ---- -- --- -------
- ----------
- ---- --------- --- ---- ----
- ----- -------- --- ---- -----
- -------- -------- ---------- --- ---- --------
- -----------
-
----- -------
------ -------------------
--------- ----------
-
- -------- --- ------------------
- ----------
- --- --- ---- --
- ----- --- ---- ----
- ------ --- ---- -----生成的HTML文档：
总结
Aglio是一个很不错的工具，可以帮助我们生成漂亮的API文档并方便地分享给其他开发者。同时，它也提供了丰富的自定义语法，可以满足大部分需求。希望本教程对你有所帮助。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/205916