If you are using markdown to write your application’s api documentation, API Blueprint will be your best choice.
API Blueprint is a specification description language based on markdown, and if you follow it to write your API specification document, you can enjoy the service of it’s supporting tools.
Syntax and Examples
Learning API Blueprint Language is very simple, as long as you have ever written something with markdown, you can quickly master it.
First, check out the official examples. You will have a big picture after reading a dozen examples.
You can then look at the Syntax Specification, current stable release is 1A9.
The official interpreter is fully supported 1A9 format. With this parser, you can easily expand their associated tools (such as code generation and so on).
Tools Supported
Editor plug-in
For those who are unfamiliar with the syntax, it is strongly recommended to install the preview plugin, alone with syntax check.
Mock Server
Both above are able to create a local mock server according to the document, which saves the time frontend developers waiting for backend developers building their server.
It is very simple to install and use them, make sure that the Node.js environment is ready:
npm install -g api-mock
api-mock ./apiary.md --port 3000
npm install -g drakov
drakov -f apiary.md -p 3000
Static HTML Generator
Aglio is a tool to generate static HTML pages according to api-blueprint document.
It is very simple to install and use them, make sure that the Node.js environment is ready:
npm install -g aglio
aglio -i foo.md -o bar.html
Getting Started
Create a new file Hello.md with the following content:
FORMAT: 1A
# Example API
hello world
## Message [/messages]
### Get Message [GET]
+ Response 200 (application/json)
{
"Hello": "world"
}
Then try
aglio -i hello.md -o hello.html
Check out the generated html document. :)
Let’s mock the server
api-mock ./hello.md --port 3000
or
drakov -f ./hello.md -p 3000
Visit localhost:3000/message. :)
Awesome, now your have a beautiful html document with a mock server.
You can also automate the releasing of api documentations with your CI server.
Happy writing api documents!
