编写API 文档

优势：工具支持多
两种编写方式
- 直接编写文档
  - 优点
    - 文档集中统一
    - 编写简单
    - 支持json,yaml格式
  - 缺点
    - 需要单独维护一份文档
- 通过代码生成
  - 优点
    - 文档注释紧密集合
  - 缺点
    - 学习成本增加，难度高，且不同语言实现方式不一致
    - 影响代码实现方式，需要修改代码
    - 文档注释依赖具体实现代码，影响阅读时间
适用于小项目

RAML

直接编写文档
- 优点
  - 可读性强
  - 支持抽象schema
  - 格式简单，工具丰富
- 缺点
  - RAML需要单独维护一套文档
RESTful API的一种简单和直接的描述，适用于大点的项目，可以有专人维护。

API blueprint

直接编写文档
安装方法

npm install -g aglio

生成html方法,支持在线预览等操作

/home/hjd/.nvm/versions/node/v7.5.0/bin/aglio -i hello.apib -o hell.html

## 主题详情 [GET /topic/{id}/{?mdrender,accesstoken}]
根据`id`获取主题详情
+ Parameters
    + id: `a2d4fa` (string) - 主题ID
    + mdrender (string,optional) - 是否渲染出现的所有 markdown 格式文本。
      + Default: `true`
    + accesstoken (string,optional) - 当需要知道一个主题是否被特定用户收藏时，才需要带此参数。会影响返回值中的 `is_collect` 值。
+ Response 200 (application/json)
    + Body
            {
                "success": true,
                "data": {
                    "id": "5433d5e4e737cbe96dcef312",
                    "author_id": "504c28a2e2b845157708cb61",
                    "tab": "share",
                    "content": "省略了……",
                    "title": "一个面向 Node.js 初学者的系列课程：node-lessons",
                    "last_reply_at": "2015-04-12T12:36:58.320Z",
                    "good": true,
                    "top": false,
                    "reply_count": 84,
                    "visit_count": 21997,
                    "create_at": "2014-10-07T12:00:36.270Z",
                    "author": {
                        "loginname": "alsotang",
                        "avatar_url": "https://avatars.githubusercontent.com/u/1147375?v=3&s=120"
                    },
                    "replies": [{
                        "id": "5433d866e737cbe96dcef313",
                        "author": {
                            "loginname": "leapon",
                            "avatar_url": "https://avatars.githubusercontent.com/u/4295945?v=3&s=120"
                        },
                        "content": "<div class=\"markdown-text\"><p>我喜欢你的写作风格</p>\n</div>",
                        "ups": ["5404a4120256839f712590f3", "50f3b267df9e9fcc58452224"],
                        "create_at": "2014-10-07T12:11:18.981Z",
                        "reply_id": null
                    },  {
                        "id": "5528eaa7831bc33a414106e2",
                        "author": {
                            "loginname": "jacksun90",
                            "avatar_url": "https://avatars.githubusercontent.com/u/8536173?v=3&s=120"
                        },
                        "content": "<div class=\"markdown-text\"><p>还不错，先收录了\n自豪地采用 <a href=\"https://github.com/lanceli/cnodejs-ionic\">CNodeJS ionic</a></p>\n</div>",
                        "ups": [],
                        "create_at": "2015-04-11T09:34:31.464Z",
                        "reply_id": null
                    }],
                    "is_collect": false
                }
            }

nginx 配置

location /sphinx {
    root /root/doc/build;  # index.html所在位置/root/doc/build/sphinx/index.html
    index index.html;
    autoindex on;
}

location /apidoc {
    root /root;
    index index.html;  # index.html所在位置/root/apidoc/index.html
    autoindex on;
} 

location /raml {
    root /root;
    index index.html;
    autoindex on;
} 
location /blueprint {
    root /root;
    index index.html;
    autoindex on;
}

上一篇 ansible操作下一篇 cobbler相关操作