https://github.com/acquia/apidoc-openapi-3
NodeJs (npm) tool to convert apidoc to OpenAPI 3.0 spec. (inspired by apidoc-swagger-3)
https://github.com/acquia/apidoc-openapi-3
Last synced: 11 days ago
JSON representation
NodeJs (npm) tool to convert apidoc to OpenAPI 3.0 spec. (inspired by apidoc-swagger-3)
- Host: GitHub
- URL: https://github.com/acquia/apidoc-openapi-3
- Owner: acquia
- Created: 2022-07-27T08:05:32.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-03-10T23:42:47.000Z (about 2 months ago)
- Last Synced: 2025-03-28T15:51:52.855Z (29 days ago)
- Language: JavaScript
- Homepage:
- Size: 106 KB
- Stars: 5
- Watchers: 6
- Forks: 4
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
## apidoc-openapi-3
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](https://github.com/apidoc/apidoc) library.
## Why use it
Inspired by [apidoc-swagger-3](https://github.com/amanoooo/apidoc-swagger-3)
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**
- **merge apidoc schema based on schema(converted by example)**
- **support auto replace mark liking {{your_tag}} with data in js/ts/json files**
- oas3.json, openapi 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](https://github.com/swagger-api/swagger-ui), [y-api](https://github.com/YMFE/yapi) to generate html overview of documentation.
`/schema/demo.js`:
```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}}
*/
```
it will output json [oas3.json](./doc/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
## Source
* [apiHooksExample](https://github.com/apidoc/apidoc-plugin-test)