Recently the company project, we need to provide a test interface documentation before is written in wiki which require time to update, but the update will often not timely, which leads to the existence of an irreconcilable conflict between the test and open. So, it is proposed that excuse documentation requirements. Based on this situation, after research found that, apidoc can solve this problem. Here's to say something about the installation apidoc.
Instructions and specifications apidoc.js
Installation Notes
In order not to pollute Everyone makes their own development environment, the following assume that you use in the docker environment, there are installation instructions => Enterprise Linux
Step 1: Install nodejs environment, there have been negligible (Please switch to the root user):
# For Node.js v6 LTS curl -silent -location https://rpm.nodesource.com/setup_6.x | bash - # When the above command is successful, you can install nodejs yum install -y nodejs.
Step 2: Install apidoc.js
# Global installation apidoc.js npm install apidoc -g # If the installation is successful, you can execute the following command to look at their own apidoc version, under normal circumstances, should be 0.17.5+ npm view apidoc version # apidoc -help will give him the supported parameters
grammar
apidoc.js supported grammar is relatively simple, all supported syntax reference http://apidocjs.com/ documents. About 10 minutes when we're finished.
specification
Configuration Specification
apidoc.json configuration file must be given, and the configuration files directory must be placed in the same project config configuration file directory. Divided into two categories:
- Entries must contain
-
- name Project name
- version version
- description Item Description
- title Browser Title
- url API request address
- Optional entry
-
- sampleUrl If you give, and you can see the input box test with the API (see Notes @ apiSampleRequest )
- header API documentation can be introduced before a markdown to do additional instructions (if you specify the directory markdown recommendations on the config directory)
- footer can be introduced later in the API documentation for a markdown to do additional instructions (if you specify the directory markdown recommendations on the config directory)
- Sequential order API interface
- template developed to show some configuration template, ajax parameters such as whether to show generation time.
One of the simplest examples (/path/to/config/apidoc.json):
{ “name”: “example”, “version”: “0.1.0”, “description”: “apiDoc basic example”, “title”: “Custom apiDoc browser title”, “url” : “https://api.github.com/v1” }
Syntax Specification
All apidoc.js comments should be placed in the controller. That directory for the file controllers. Notes is currently divided into two categories, one for the class, the other on the method.
Class Notes
The comment refers to the class SomeController placed on this line comments. Usually a global role, and such comments can only appear here. Currently there is only one such comment
Method Notes
That comment function should be placed on actionSome this line. Such comments must appear here. A need for a method of routing (i.e., prefix-action, require annotation) for all the controller inside. All comments API must contain the following information:
- @api comprising path request and the request method request header
- @apiName request method name
- @apiGroup request belongs to the group
- @apiSuccessExample request was successful examples
The following comments are optional:
- @apiParam request parameters, if there is the API request parameters, must bring this note, and your parameters might detail. When necessary, can bring @apiParamExample for learning
- The interface requires authorization whether @apiPermission
- @apiUse use @apiDefine defined out of something
- @apiVersion version
- @apiHeader request header
- @apiDprecated
- @apiSampleRequest demonstrates how to request
A complete presentation as follows:
/**
* @api {get} microCommunity/Vote/list 点赞列表
*
* @apiDescription 获取指定用户的点赞列表或者被点赞列表.
*
* @apiName list
* @apiGroup vote
*
* @apiParam {String} [uid=当前登录用户] 需要查询的用户id.
* @apiParam {String} [offset=null] 分页时需要的偏移量，该值会在第一次请求之后返回供客户端使用.
* @apiParam {Integer} [size=10] 期望分页返回的数据页大小.
* @apiParam {Enums(String)} [type=liked] 类型，分为(`liked`:点赞)和(`beliked`:被点赞).
*
* @apiSuccessExample Success-Response://这里的JSON可以不用格式化，因为apidoc.js会自动格式化,但是最好格式化放在这里，方便别人看.
* {
* "data": {
* "offset": null, // 返回null则表示没数据了。
* "size": 10,
* "current_size": 1, // 当前页实际大小.
* "data": [
* {
* "_id": "58fd6895ce1cdd222bb23bc0",
* "uid": "fengxingchao", // 点赞人ID
* "target": "fenghaiting", // 被点赞人ID
* "action": "like", // 动作类型，目前仅有like一种,此action对前端无用，无需关心.
* "create_time": 1493002389, // 点赞时间.
* "update_time": 1493002389, // 点赞更新时间.
* "create_time_fmt": "2017-04-24 10:04:09", // 点赞时间
* "update_time_fmt": "2017-04-24 10:04:09", // 点赞更新时间
* "message": "你好啊", // 点赞理由.
* "targetprofile": { // 被点赞人信息
* "avatar": "http://shp.qpic.cn/bizmp/9Qe6l7LKo9miapKGAM5WOye63YoztzaH1XqEFsDlgRGpbH7DYAtAzmA/",
* "email": "[email protected]",
* "gender": "1",
* "mobile": "xxxxxxx",
* "name": "测试1",
* "userid": "fenghaiting"
* },
* "uidprofile": { // 点赞人信息
* "avatar": "http://shp.qpic.cn/bizmp/9Qe6l7LKo9mk50V8VSNiamg0h6ibtLicBAosek11EcDyjEXQCkOlvXaiaQ/",
* "email": "[email protected]",
* "gender": "1",
* "mobile": "xxxxxxxx",
* "name": "测试",
* "userid": "fengxingchao"
* }
* }
* ]
* },
* "status": 200,
* "message": "ok"
* }
*/