APIDOC In A Nutshell
0 likes217 views
This document discusses APIDOC, an inline documentation tool for RESTful APIs. It can be used with various programming languages by including documentation comments. APIDOC parses these comments to generate API documentation that describes endpoints, parameters, responses and errors. It has a simple structure for organizing comments and can be installed via CLI tools or build tools like Grunt or Gulp. Configuration options allow customizing the generated documentation.
![Structure
/**
* @api {put} /user/:id Modify User information
* @apiName PutUser
* @apiGroup User
*
* @apiParam {Number} id Users unique ID.
* @apiParam {String} [firstname] Firstname of the User.
* @apiParam {String} [lastname] Lastname of the User.
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* @apiErrorExample Response (example):
* HTTP/1.1 400 Bad Request
* {
* "error": "UserNameTooShort"
* }
*/](https://image.slidesharecdn.com/apidocinanutshell-160913044729/85/APIDOC-In-A-Nutshell-13-320.jpg)
APIDOC In A Nutshell
- 1. APIDOC in a nutshell Inline Documentation for RESTful web APIs Ben
- 2. Why APIDOC?
- 3. Java, JavaScript, PHP, C#, GO, … /** * @api {get} /user/:id Request User information * @apiName GetUser * @apiGroup User * * @apiParam {Number} id Users unique ID. * * @apiSuccess {String} firstname Firstname of the User. * @apiSuccess {String} lastname Lastname of the User. */ CoffeeScript ### @api {get} /user/:id Request User information @apiName GetUser @apiGroup User @apiParam {Number} id Users unique ID. @apiSuccess {String} firstname Firstname of the User. @apiSuccess {String} lastname Lastname of the User. ### Python “”” @api {get} /user/:id Request User information @apiName GetUser @apiGroup User @apiParam {Number} id Users unique ID. @apiSuccess {String} firstname Firstname of the User. @apiSuccess {String} lastname Lastname of the User. “”” Ruby =begin @api {get} /user/:id Request User information @apiName GetUser @apiGroup User @apiParam {Number} id Users unique ID. @apiSuccess {String} firstname Firstname of the User. @apiSuccess {String} lastname Lastname of the User. =end
- 5. Installation cli gulp grunt npm install apidoc -g npm install grunt-apidoc --save-dev npm install gulp-apidoc --save-dev
- 6. Structure /** * @api {post} /login Login * @apiVersion 1.1.2 * @apiName Login * @apiGroup Auth * * @apiParam {String} username Username * @apiParam {String} password User password * * @apiSuccess {String} token token * @apiSuccess {String} data token */ /** * @api {get} /blockstorage/v1 Get blockstorage welcome message * @apiVersion 1.1.2 * @apiName WelcomeMessage * @apiGroup BlockStorage * @apiHeader {String} Authorization Bearer token value. * * @apiSuccess {String} welcomeMsg "This is blockstorage service." */
- 7. Structure /** * @api {post} /login Login * @apiVersion 1.1.2 * @apiName Login * @apiGroup Auth * * @apiParam {String} username Username * @apiParam {String} password User password * * @apiSuccess {String} token token * @apiSuccess {String} data token */ /** * @api {get} /blockstorage/v1 Get blockstorage welcome message * @apiVersion 1.1.2 * @apiName WelcomeMessage * @apiGroup BlockStorage * @apiHeader {String} Authorization Bearer token value. * * @apiSuccess {String} welcomeMsg "This is blockstorage service." */
- 8. Structure /** * @api {post} /login Login * @apiVersion 1.1.2 * @apiName Login * @apiGroup Auth * * @apiParam {String} username Username * @apiParam {String} password User password * * @apiSuccess {String} token token * @apiSuccess {String} data token */ /** * @api {get} /blockstorage/v1 Get blockstorage welcome message * @apiVersion 1.1.2 * @apiName WelcomeMessage * @apiGroup BlockStorage * @apiHeader {String} Authorization Bearer token value. * * @apiSuccess {String} welcomeMsg "This is blockstorage service." */
- 9. Structure /** * @api {post} /login Login * @apiVersion 1.1.2 * @apiName Login * @apiGroup Auth * * @apiParam {String} username Username * @apiParam {String} password User password * * @apiSuccess {String} token token * @apiSuccess {String} data token */ /** * @api {get} /blockstorage/v1 Get blockstorage welcome message * @apiVersion 1.1.2 * @apiName WelcomeMessage * @apiGroup BlockStorage * @apiHeader {String} Authorization Bearer token value. * * @apiSuccess {String} welcomeMsg "This is blockstorage service." */
- 10. Structure /** * @api {post} /login Login * @apiVersion 1.1.2 * @apiName Login * @apiGroup Auth * * @apiParam {String} username Username * @apiParam {String} password User password * * @apiSuccess {String} token token * @apiSuccess {String} data token */ /** * @api {get} /blockstorage/v1 Get blockstorage welcome message * @apiVersion 1.1.2 * @apiName WelcomeMessage * @apiGroup BlockStorage * @apiHeader {String} Authorization Bearer token value. * * @apiSuccess {String} welcomeMsg "This is blockstorage service." */
- 11. Structure /** * @api {post} /login Login * @apiVersion 1.1.2 * @apiName Login * @apiGroup Auth * * @apiParam {String} username Username * @apiParam {String} password User password * * @apiSuccess {String} token token * @apiSuccess {String} data token */ /** * @api {get} /blockstorage/v1 Get blockstorage welcome message * @apiVersion 1.1.2 * @apiName WelcomeMessage * @apiGroup BlockStorage * @apiHeader {String} Authorization Bearer token value. * * @apiSuccess {String} welcomeMsg "This is blockstorage service." */
- 12. Structure /** * @api {post} /login Login * @apiVersion 1.1.2 * @apiName Login * @apiGroup Auth * * @apiParam {String} username Username * @apiParam {String} password User password * * @apiSuccess {String} token token * @apiSuccess {String} data token */ /** * @api {get} /blockstorage/v1 Get blockstorage welcome message * @apiVersion 1.1.2 * @apiName WelcomeMessage * @apiGroup BlockStorage * @apiHeader {String} Authorization Bearer token value. * * @apiSuccess {String} welcomeMsg "This is blockstorage service." */
- 13. Structure /** * @api {put} /user/:id Modify User information * @apiName PutUser * @apiGroup User * * @apiParam {Number} id Users unique ID. * @apiParam {String} [firstname] Firstname of the User. * @apiParam {String} [lastname] Lastname of the User. * * @apiSuccessExample Success-Response: * HTTP/1.1 200 OK * @apiErrorExample Response (example): * HTTP/1.1 400 Bad Request * { * "error": "UserNameTooShort" * } */
- 14. Settings //package.json { "name": "cc-backend", "description": "An ultimate cloud service that rules the world.", "version": "1.1.2", "apidoc": { "title": "cc api document", "url": "http://cc.api.hopebaytech.com/api", "sampleUrl": "http://cc.api.hopebaytech.com/api" } }
- 15. Live Demo && Q&A