apidoc-swagger-converter
v1.0.9
Published
Convert api doc json to swagger-3.0 json
Downloads
15,465
Maintainers
Readme
apidoc-swagger-converter
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,
such as
- distinguish Query or Body in Post request
- @apiHeader
- old repo not suppport multi input dirs
and this repo add new feature
- support convert apidoc example to swagger schema
- converts nested arrays into swagger schema
- reads base apidoc.json config file
- merge apidoc schema based on schema(converted by example)
- support auto replace mark liking {{your_tag}} with data in js/ts/json files
- swagger.json version 3.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
* {{extraExample}}
*
* @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
}
}
*
* @apiSuccessExample {json} error_desc
* HTTP/1.1 300 OK
* {{fooInJs:barInJs}}
*/
Then run the command to generate swagger.json
it will output json swagger.json
Tips
you should always use command apidoc-swagger-converter directly, if you use npx apidoc-swagger-converter, this lib is not able to find hook, replacing mark would be failed