amanoooo / apidoc-swagger-3

apidoc-openapi-3.0

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.

Why use it

Inspired by apidoc-swagger

The old repo may not be maintained, and not support new api-doc feature

and this repo add new feature

• **support convert body parameters schema for openapi 3.0.0 **
• **support convert header/query parameters schema for openapi 3.0.0 **

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, y-api to generate html overview of documentation.

/schema/demo.js:

/**
* @api {post} /test_api desc_test_api
* @apiName test_api_name
* @apiGroup search
*
* @apiHeader {String} [taz] desc_taz
*
* @apiParam {Number} [tar] desc_tar
* @apiParam (Body) {Object[]} foo desc_foo
* @apiParam (Body) {String} foo.foz desc_foo.foz
* @apiParam (Query) {String} bar=bar desc_bar
*
* @apiParamExample {json} request_desc
* {
    "data": {
        "keyInReq": "v1"
  }
}
*
* @apiSuccess {Number} [code=1] desc_override_code
* @apiSuccess {Object} data data_desc
* @apiSuccess {number} data.keyInDoc desc_add_extra_data_key_in_doc
*
* @apiSuccessExample {json} response_desc
* HTTP/1.1 200 OK
*  {
   "code": 200,
    "data": {
        "keyInExample": 1
  }
}
*
*/

it will output json swagger.json

Tips

you should always use command

apidoc-openapi-3

directly, if you use

npx apidoc-openapi-3

, this lib is not able to find hook, replacing mark would be failed