This article has participated in the “Digitalstar Project” and won a creative gift package to challenge the creative incentive money.

The installation

  1. Installation node. Js

  2. Install apiDoc in the project root directory

    npm install apidoc -g

configuration

Create a new apidoc.json file in your project root directory. This file describes the outline of the interface provided by the project, such as name, version, description, the title displayed by the browser when the document is opened, and the default access address of the interface. apidoc.json

{"name": "ServiceEbikeAPIs", "version": "3.1.0", "description": "Vehicle Service API documentation ", "title": "ServiceEbikeAPIs"," URL ": "http://cjl3.rokyinfo.net:7190/api-ebike" }Copy the code

Finally generate project root directory, one level up

apidoc -i otc-audit-end/application -o otc-audit-end/public

Use the sample

/** ** @apidefine RkNotFoundException ** @apierror RkNotFoundException could not find relevant data ** @apierRorexample Error-Response: * HTTP/1.1 404 Not Found * {* "error": {* "code": 404, * "MSG ": "", * * * "path" ""}} / / * * * * * * @ API {get} / v3.1 / ues / : sn/rt - info for equipment to real-time information * @ apiVersion 3.1.0 * @ apiName GetUeRealTimeInfo * @apigroup UE * * @APIHeader {String} Authorization User Authorization token * @APIheader {String} firm firm number * @apiHeaderExample {json} Header-Example: * { * "Authorization": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOjM2NzgsImF1ZGllbmNlIjoid2ViIiwib3BlbkFJZCI6MTM2NywiY3JlYXRlZCI6MTUzMzg3OTM2ODA0Nywicm9sZX MiOiJVU0VSIiwiZXhwIjoxNTM0NDg0MTY4fQ.Gl5L-NpuwhjuPXFuhPax8ak5c64skjDTCBC64N_QdKQ2VT-zZeceuzXB9TqaYJuhkwNYEhrV3pUx1zhMWG7 Org", * "firm": "CnE =" *} * * @APIParam {String} sn Device SN * * @APisuccess {String} sn Device SN * @APisuccess {Number} status Device status * @APisuccess {Number} Percentage of soc battery power * @APisuccess {Number} voltage Battery voltage * @APisuccess {Number} current battery current * @APisuccess {Number} temperature battery temperature * @apisuccess {String} reportTime reportTime (yyyy-mm-dd HH: MM :ss) * * @apisuccessexample Success-response: * HTTP/1.1 200 OK * {* "SN ": "P000000000", * "status": 0, * "soc": 80, * "voltage": 60.0, * "current": 10.0, * "temperature": null, * "reportTime": "2018-08-13 18:11:00" * } * * @apiUse RkNotFoundException * */ @RequestMapping(value = "/{sn}/rt-info", method = RequestMethod.GET) public UeRealTimeInfo getUeRealTimeInfo(@RequestHeader(Constants.HEADER_LOGIN_USER_KEY) long  userId, @PathVariable("sn") String sn) { return ueService.getRealTimeInfo(sn); }Copy the code

@api

@api {method} path [title]
Copy the code

HTTP interface calls method, path, and name

@apiVersion

@apiVersion version
Copy the code

API version number

@apiName

@apiName name
Copy the code

The name of the API

@apiGroup

@apiGroup name
Copy the code

API group

@apiHeader

@apiHeader [(group)] [{type}] [field=defaultValue] [description]
Copy the code

Request header parameter

@apiParam

@apiParam [(group)] [{type}] [field=defaultValue] [description]
Copy the code

Request parameters

@apiSuccess

@apiSuccess [(group)] [{type}] field [description]
Copy the code

Return data description

@apiSuccessExample

@apiSuccessExample [{type}] [title]
                   example
Copy the code

The interface returns an example successfully. Procedure

@apiError

@apiError [(group)] [{type}] field [description]
Copy the code

Interface failure description

@apiErrorExample

@apiErrorExample [{type}] [title]
                 example
Copy the code

An example is returned if the interface fails

@apiDefine

@apiDefine name [title]
                     [description]
Copy the code

Similar to macro definitions, they can be referenced

@apiUse

@apiUse name
Copy the code

Use the description defined by @apidefine

Please refer to the official documentation apidocjs.com for more detailed instructions

Generating documentation

CD Go to the apidoc.json directory (the root directory of the project) and run the following command

apidoc -i src/ -o apidoc/
Copy the code

After the command is executed successfully, the apidoc folder is generated, as shown in the following figure

The picture

Click on index.html in the apidoc folder to find the nice API documentation that has been generated

The picture

Thumb up 15 people

Technical management

Author: Yuan Zhijian links: www.jianshu.com/p/34eac66b4… The copyright of the book belongs to the author. Commercial reprint please contact the author for authorization, non-commercial reprint please indicate the source.

​