Under the api-blueprint spec to define project apis, we use aglio to convert .apib files into .html page for sharing purpose. We also use drakov to mock data in .apib files during early developing stage.
But there're drawbacks:
-
Aglio isn't friendly to big api base. We have to split big api base into small ones to achieve a proper html page size.
-
Drakov is slow to run on big api base. It faces the same problem as the aglio.
-
We have to use different commands to obtain the api document and the mock server. It's tedious.
Here we have apidox-cli.
It is an api-blueprint-friendly tooling which can
-
start a document server (use
-poption), serving generated html from api blueprint files (*.apib). -
start a mock server (use
-Poption), using data in api blueprint files as response payload.
We treat sub-folder as modules. If sub-folder is detected, a menu will be automatically generated.
Eventually, all you have to do is focuing on writing api-blueprint docs, leaving the rest things to apidox-cli.
- Each sub-folder (we call it module) requires a header-file, which configs the
BASE_URIand the module title.- Api definations should all be grouped.
npm i apidox-cli
apidox <folder> [options]
| options | description | required | default |
|---|---|---|---|
-p <docPort> |
document server port | -- | 4002 |
-P <mockPort> |
mock server port | -- | -- |
-t <theme> |
one of default, cyborg, flatly, slate, streak or 0-4 |
-- | streak |
- start a document server:
apidox ./examples - start a mock server:
apidox ./examples -P 3000 - start document server and mock server:
apidox ./examples -p 4002 -P 3000 - change document theme:
apidox ./examples -t 2
MIT