Skip to content

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 to json schema and later convert it to swagger json schmea.

License

Notifications You must be signed in to change notification settings

socialtables/apidoc-swagger

 
 

Repository files navigation

apidoc-swagger

Build Status: CircleCI

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/

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.

About

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 to json schema and later convert it to swagger json schmea.

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • JavaScript 100.0%