刘贵学博客

如何写 RESTful API 文档

本文使用 apidoc 工具自动生成 RESTfull API 格式的文档

安装

npm install apidoc -g

cd rest/doc
./doc.sh

产生的 手册文件存放在 doc/gen 目录下,打开index.html 即可使用。

使用方法

基于注释,按标记 自动提取文档内容, 类似写法如下:

 /**
 * @api  {get}  /v1/focus/:id/:focus
 * @apiGroup Projecting
 * @apiDescription  关注或取消关注项目。 注:用于App
*/

参数说明:


更多明细,请参考: http://apidocjs.com/#param-api

生成的文档如下图:

RESTful 测试工具

  1. 命令行工具可以使用 curl 工具:

  • get 方法

    curl \
    localhost:7999/v1/projecting/5964ba8c34be4904b70394bf
    
  • post 方法

    curl -l -H "Content-type: application/json" -X POST \
    localhost:7999/v1/projecting/5964ba8c34be4904b70394bf  -d \
    '["59644de76ab75d074f300a5b","5966472e79478d0e2547c7a3"]'
    
  1. 图形化的建议使用 PostMan, 使用方法: