In this small guide we’ll go through a couple of basic elements of API Blueprint and writing API documentation in the blueprint format.
Let’s get started
OK, there’s one thing we need to do before we start – we need to define a resource (User). We’ll be using it as an example that has endpoints for register and login. Our first step is to go through basic syntax for writing documentation, and then I’ll show you what all of this looks like after we put it together.
How to define resources and routes
To define a resource, we need to use a single hashtag – #. For example: # User Group. It’s that simple.
We also need to define an endpoint route for registration – let’s say /register. We do this by using a double hashtag ## for naming and box brackets  for naming a particular endpoint route. This could look like: ## Registration [/register].
Now that we covered defining resources and routes, let’s continue.
How to define request and response with attributes
To define a specific request, we first need to define its type. Registration request would be obviously POST request. In order to define a request, we need to use the triple hashtag sign ###, and we use the space between  to define its type and route. After we’ve done all of that, we end up with something like this: ### Registration [POST /register]
We know the basics, now let’s define request attributes and its types. You do it like this:
+ Request (application/json) + Attributes + username: `JohnD` (string, required) + email: `firstname.lastname@example.org` (string, required) + years: 38 (number) + password: `mySecret` (string, required)
And now we’re ready to define a response. We do it by doing this:
+ Response 201 (application/json) + Attributes + token: `aabbccdd1234` (string) - access token + user (User)
As you can see, you can easily specify types for a particular attribute. We have some primitive types like string, number and boolean, but we can also use structure types like array, enum and object.
Another thing you can make are your own objects which will be used as types.
# Data Structure ## User + id: 1245 (number) + userId: 1 (number) + comments: (array[UserComment])
Rendering an API blueprint into html
The last thing we’ll cover in this quick guide is rendering an API blueprint into html, and this one is quite simple. If you’re using Aglio, rendering a blueprint into html is as easy as aglio -i input.apib -o output.html.
And that’s it – now you know the basics of API Blueprint.
We’re available for partnerships and open for new projects. If you have an idea you’d like to discuss, share it with our team!