apidoc-swagger

Build status:

apidoc and swagger are two nice projects which are focusing on documentation of APIs. This project is a middle tier which tries to bring them together in a sense that:

It uses apidoc to convert inline documentation comments into json schema and later convert it to swagger json schema.

Uses the apidoc-core library.

How It Works

By putting in line comments in the source code like this in javascript, you will get swagger.json file which can be served to swagger-ui to generate html overview of documentation.

/api/foo.js:

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

Installation

npm install apidoc-swagger -g

Current version unlocks most of the basic capabilities of both projects and improvement is in progress.

Example

apidoc-swagger -i example/ -o doc/

Options

The following options can be used to customize the behavior of apidoc-swagger:

| Long Name | Abbreviation | Default | Description | | --------- | ------------ | ------- | ----------- | | --input | -i | REQUIRED | Input / source dirname. | | --file-filters | -f | .*\\.(clj|coffee|cs|dart|erl|go|java|scala|js|php?|py|rb|ts|pm)$ | RegEx-Filter to select files that should be parsed. | | --exclude-filters | -e | | RegEx-Filter to select files / dirs that should not be parsed. | | --output | -o | ./doc/ | Output dirname. | | --verbose | -v | false | Vebose debug output. | | --help | -h | | Shows help information | | --debug | | false | Show debug message | | --color | | true | Turn off log color | | --host | | | target host to use instead of url in package.json/apidoc.json | | --default-response | | false | uses default success responses instead of api doc generated responses | | --base-path | | / | basepath for the api | | --schemes | | http | comma separated list of url schemes | | --parse | | false | Parse only the files and return the data, no file creation. | | --parse-filters | | | Optional user defined filters. Format name=filename. | | --parse-languages | | | Optional user defined languages. Format name=filename. | | --parse-parsers | | | Optional user defined parsers. Format name=filename | | --parse-workers | | | Optional user defined workers. Format name=filename | | --silent | | false | Turn all output off | | --simulate | | false | Execute but don't create output file | | --markdown | | false | Turn on markdown parser | | --marked-config | | | Enable custom markdown parser configs. It will overwite all other marked settings. | | --marked-gfm | | false | Enable GitHub flavored markdown. | | --marked-tables | | false | Enable GFM tables. This option requires the gfm option to be true. | | --marked-breaks | | false | Enable GFM line breaks. This option requires the gfm option to be true. | | --marked-pedantic | | false | Conform to obscure parts of markdown.pl as much as possible. | | --marked-sanitize | | false | Sanitize the output. Ignore any HTML that has been input. | | --marked-smartLists | | false | Use smarter list behavior than the original markdown. | | --marked-smartypants | | false | Use 'smart' typograhic punctuation for things like quotes and dashes. |

Have a look at apidoc for full functionality overview and capabilities of apidoc.

To read more about how swagger works refer to swagger-ui and swagger-spec for details of swagger.json.

Gulp Module

gulp-apidoc-swagger npm install gulp-apidoc-swagger.