Skip to content

This API will read annotations of the project APIs and create a PDF document with there Request and Response.

Notifications You must be signed in to change notification settings

Hestabit/node-api-doc-generator

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

2 Commits
 
 
 
 
 
 
 
 
 
 

Repository files navigation

APIs Documentation

This API will read annotations of the project APIs and create a PDF document with there Request and Response.

Installation

Step 1: Run npm install apidoc -g in your terminal (It will install apidoc in your system globally)

$ npm install apidoc -g

Step 2: Install node-api-doc-generator

$ npm install node-api-doc-generator

Step 3: Required node-api-doc-generator in your app.js / index.js (entry point) or into your routes file and provide the app, hostname, port as in parameter.

const nodeApiDocGenerator = require('node-api-doc-generator')
nodeApiDocGenerator(app,'hostname',port)

or 

require('node-api-doc-generator')(app,'hostname',port);

Step 4 : Finaly start your server and hit /api/document in your browser to generate the APIs document. (It will create a new document at your root directory with the name api_document.pdf.)

--


How it works

  • It read all the mentioned annotations of the APIs
  • Then it calls all the APIs (which contain their annotations according to apidoc) and provides the random input as per API requirement.
  • Then it stores the request (Input) and the response (Output) of each API.
  • Finally, it creates the PDF documentation of APIs which contain - apiName, apiMethod, apiUrl, apiDescription, apiParams,apiSuccess,apiRequest,apiResponse

Conditions

  • It only works if you mention annotations of API.
  • Annotations should be according to "apidoc" for more details visit the official site of apidoc
  • It supports GET, POST, PUT and DELETE method.

--


Annotations

Minimum annotation required by the API is given below -

/**
 * @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.
 */

Explanation

@api

@api {method} path [title]

Required!

Without that indicator, apiDoc parser ignore the documentation block. The only exception are documentation blocks defined by @apiDefine, they not required @api.

Usage: @api {get} /user/:id Users unique ID.

Name Description
method Request method name: DELETE, GET, POST, PUT
path Request Path.
title A short title. (used for navigation and article header)

Example:

/**
 * @api {get} /user/:id
 */

@apiName

@apiName name

Should always be used.

Defines the name of the method documentation block. Names will be used for the Sub-Navigation in the generated output. Structure definition not need @apiName.

Usage: @apiName GetUser

Name Description
name Unique name of the method. Format: method + path (e.g. Get + User), only a proposal, you can name as you want. Also used as navigation title.

Example:

/**
 * @api {get} /user/:id
 * @apiName GetUser
 */

@apiGroup

@apiGroup name

Should always be used.

Defines to which group the method documentation block belongs. Groups will be used for the Main-Navigation in the generated output. Structure definition not need @apiGroup.

Usage: @apiGroup User

Name Description
name Name of the group. Also used as navigation title.

Example:

/**
 * @api {get} /user/:id
 * @apiGroup User
 */

@apiParam

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

Describe a parameter passed to you API-Method.

Usage: apiParam (MyGroup) {Number} id Users unique ID.

Name Description
(group) optional All parameters will be grouped by this name. Without a group, the default Parameter is set. You can set a title and description with @apiDefine.
{type} Parameter type, e.g. {Boolean}, {Number}, {String}, {Object}, {String[]} (array of strings), ...
field Variablename.
[field] Fieldname with brackets define the Variable as optional.
=defaultValue optional The parameters default value.
description Description of the field.

Example:

/**
 * @api {get} /user/:id
 * @apiParam {Number} id Users unique ID.
 */
 
 /**
 * @api {post} /user/
 * @apiParam {String} [firstname]  Optional Firstname of the User.
 * @apiParam {String} lastname     Mandatory Lastname.
 * @apiParam {String} country="DE" Mandatory with default value "DE".
 * @apiParam {Number} [age=18]     Optional Age with default 18.
  */

@apiSuccess

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

Success return Parameter.

Usage:@apiSuccess {String} firstname Firstname of the User.

Name Description
(group) optional All parameters will be grouped by this name. Without a group, the default Success 200 is set. You can set a title and description with @apiDefine.
{type} Parameter type, e.g. {Boolean}, {Number}, {String}, {Object}, {String[]} (array of strings), ...
field Return Identifier (returned success code).
description Description of the field.

Example:

/**
 * @api {get} /user/:id
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 */

Errors

We create a error.log file at the root folder of the project.

About

This API will read annotations of the project APIs and create a PDF document with there Request and Response.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published