Guide to Creating Detailed API Documentation with API Blueprint

Why Do We Need API Documentation?

In today’s modern software development world, APIs (Application Programming Interfaces) act as bridges between systems, applications, and teams. However, a sad reality many developers face is the lack of API documentation or poor-quality documentation.

Imagine you're a frontend developer tasked with integrating a new API. You open the documentation and only see a dry list of endpoints, with no concrete examples of requests and responses. You start “guessing” — trying different parameters, inspecting responses to understand the data structure. Time passes, the deadline is approaching, and you're still struggling with mysterious 400 Bad Request errors.

This scenario doesn’t just happen to frontend developers. Backend teams often receive repetitive questions like: “Is this parameter required?”, “What does the error response look like?”, “How do we authenticate?”. This lack of synchronized information creates a vicious cycle — teams constantly interrupt each other for clarification, affecting productivity on both sides.

The problem becomes even more serious when a new developer joins the team. Instead of being able to self-learn and get familiar with the system through documentation, they rely on direct guidance from experienced colleagues or have to dig through source code, adding more burden to the entire team.

API Blueprint and aglio – The Perfect Solution for API Documentation

This is where API Blueprint emerges as an optimal solution. API Blueprint is an API description language that uses Markdown-like syntax to describe RESTful APIs in a visual and easy-to-understand way. What’s special about API Blueprint is its philosophy: “human-first, machine-second” — meaning you can write documentation in natural language that closely resembles familiar Markdown formatting.

To transform these API Blueprint files into beautiful, interactive HTML documentation, we use aglio — a compiler written in Node.js. Aglio acts like “magic,” converting simple text lines in .apib files into professional documentation pages with a modern interface.

Why is API Blueprint + aglio so effective?

The power of this duo lies in its simplicity and strength.

First, the syntax is almost identical to Markdown, making it extremely easy to learn and maintain. If you’ve ever written a README on GitHub or documentation on other platforms, you’ll feel instantly familiar. No need to learn complex languages like JSON Schema or YAML with hundreds of hard-to-remember attributes.
Second, aglio doesn’t just generate static HTML — it integrates interactive examples directly into the documentation. Readers can view request/response structures, experiment with different parameters, and understand how the API works without needing any external tools. This significantly reduces onboarding time and prevents misunderstandings.
A particularly exciting feature is the ability to automatically generate mock servers from the specification. This means that even if the backend team hasn’t finished the API, the frontend team can start development and testing with mock data that has the correct structure. This parallel workflow greatly accelerates development speed.
Since .apib files are plain text, they are fully compatible with version control systems. You can easily track changes, resolve merge conflicts, and review via pull requests just like regular source code. No more comparing complex binary files or switching between different tools.
Finally, the workflow is extremely streamlined: write specification → convert to HTML → review → deploy. This entire process can be fully automated, from auto-building on changes to deploying on platforms like GitHub Pages or S3.

Setting Up the Environment

Alright, now that we’ve covered the theory, it’s time to roll up our sleeves and get hands-on.

Step 1: Install Node.js

Since aglio is built on Node.js, you need to install Node.js first. Visit nodejs.org and download the LTS (Long Term Support) version — this is the most stable version recommended for production environments. The installation process is straightforward; just follow the on-screen instructions.

To verify that everything is installed correctly, open Terminal (macOS / Linux) or Command Prompt (Windows) and run the following commands:

node -vnpm -v

If Node.js is installed, you’ll see the version displayed, for example:

v18.17.1

Step 2: Install aglio

Once Node.js is installed, installing aglio is very simple. Open Terminal (macOS / Linux) or Command Prompt (Windows) and run:

npm install -g aglio

The -g flag installs aglio globally, meaning you can use the aglio command from any directory on your system.

To verify the installation, run:

aglio --version

If the command returns a version number — congratulations! You’ve successfully set up the environment and are ready to create your first API documentation.

Step 3: Quick Start with a Prebuilt Template

Instead of figuring out the API Blueprint structure from scratch, I’ve prepared a sample source for you to reference. You can download it from here.

Build and Preview the Result

Now, run the following command inside the repository containing the sample source to convert the API Blueprint file into HTML:

aglio -i index.apib -o index.html

After building, open the index.html file in your browser to view the result. You’ll see a complete API documentation with:

A navigation menu on the left
Interactive request/response examples
A professional and responsive interface

Try Different Themes

If you find the default theme hard to read — don’t worry! Aglio offers various themes you can customize to your liking. For more details on available themes and rendering options, visit the aglio GitHub page and check the README.md.

For example, to generate documentation with a more professional 3-column layout, run:

aglio -i index.apib --theme-template triple -o index.html

Structure of an API Blueprint

Now that you have the environment and template ready, let’s explore the structure and syntax of an API Blueprint. A basic API Blueprint for beginners typically includes the following:

Header and Metadata
API groups by functionality
Resources: smaller API groups sharing the same URI
Individual APIs under each group or resource

Example:

FORMAT: 1A
HOST: https://api.example.com

# My API Documentation
This is an API template for reference purposes only.

# Group Common
Includes descriptions of common specifications such as validation rules, error formats, message lists, pagination specifications, etc.

# Group User
User management in the system

### userSearch [GET /users{?name,email,sort,page}]
Search all users in the system.

### userCreate [POST /users]
Create a new user in the system.

## userById [/users/{id}]

### userGetById [GET]
Get user information by ID

### userUpdate [PUT]
Update user information.

### Delete User [DELETE]
Delete a user from the system.

◆ Header and Metadata (optional)

Every API Blueprint file starts with basic information:

FORMAT: 1A
HOST: https://api.yourcompany.com/v1

# API Title
Brief description of the API

FORMAT: 1A is the spec version — just leave it as is.
HOST is the base URL that clients will call.
The title after # will appear prominently at the top of the documentation.
The API Title is marked with #, which is Markdown syntax for Heading 1.
The Brief description provides context for readers, such as what system the API belongs to, author info, and last update time.

◆ Group

If your system only has a few APIs with unrelated functions, grouping them may not be necessary. But in reality, most systems have dozens or even hundreds of APIs, clearly divided into functional groups such as: authentication and authorization, user management, order management, invoice management...

Instead of listing all APIs separately, we can group them by functionality using the syntax # Group {group name}.

Example:

# Group authentication
API endpoints for login, logout, and token management.

# Group user
Manage user information in the system.

# Group order
Create, track, and process orders.

After rendering to HTML, APIs under a group will be displayed together in a structured format.

◆ Resource (optional)

When multiple APIs (e.g., userGetById, userUpdate, userDelete) share the same URI, they should be placed under the same resource (e.g., ## userById [/users/{id}]). If you separate them like:

### userGetById [GET /users/{id}]

### userUpdate [PUT /users/{id}]

### userDelete [DELETE /users/{id}]

Aglio will throw a syntax error when building the HTML.

◆ API Specification

This is the most important part of an API Blueprint document. The structure of an API depends on its functionality, but generally includes:

API Name – Method – URI: Appears on a single line, typically starting with a heading like ###.
Brief description of the API’s purpose: For example, searching users or creating a new user.
Detailed explanation of internal processing: Such as validation checks, search logic, database operations...

Input Description

Can be either Parameters, Request, or both.

◇　If using Parameters:

Declare them both in the URI and under + Parameters.
Each parameter line includes:
- Physical name after +
- Example value separated by : (strings should be wrapped in backticks)
- Data type and whether it’s required (inside parentheses, separated by comma)
- Logical name after a dash -

Example:

### userSearch [GET /users{?name,email,ageFrom,ageTo,page,limit}]

* Search for users in the system based on specified criteria

#### Search Processing

* [Parameters.name]: Add search condition [users.name] LIKE '%[Parameter.name]%'
* [Parameters.email]: Add search condition [users.email] LIKE '%[Parameter.email]%'
* [Parameters.ageFrom]: Add search condition [users.age] >= %[Parameter.ageFrom]%
* [Parameters.ageTo]: Add search condition [users.age] <= %[Parameter.ageTo]%
* [Parameters.page], [Parameters.limit]: See [Common pagination spec](#pagination)

+ Parameters
    + name: `John` (string, optional) - Name
    + email: `john@example.com` (string, optional) - Email address
    + ageFrom: 18 (number, optional) - Age from
    + ageTo: 25 (number, optional) - Age to
    + page: 1 (number, optional) - Page number
    + limit: 20 (number, optional) - Items per page

◇　If using Request:

No need to declare in URI, just declare them under + Request.
Immediately after Request, specify the Content-Type (e.g., application/json, multipart/form-data, application/x-www-form-urlencoded).
Declare request paramaters it under + Attributes, similar to + Parameters.

Example:

### userCreate [POST /users]

* Create a new user based on the received information

#### Validation

* Check required:
    * [Request.name]
    * [Request.email]
* Check length:
    * [Request.name]: max 50
    * [Request.email]: max 255
    * [Request.age]: max 3
* Check format:
    * [Request.email]: RFC standard email format
    * [Request.age]: positive integer only

#### Save Processing

* Insert new record into [users] table
    * [name] = [Request.name]
    * [email] = [Request.email]
    * [age] = [Request.age]

+ Request (application/json)
    + Attributes (object)
        + name: `John Doe` (string, required) - Full name
        + email: `john@index.com` (string, required) - Email address
        + age: 25 (number, optional) - Age in years

Output Description

This is a required part of any API and includes:

HTTP status codes: Declared right after + Response
Content-Type of the response: e.g., application/json, multipart/form-data, application/pdf, application/octet-stream, etc.
Response content: If available, declare it under + Attributes, similar to how you declare request parameters.

Example:

+ Response 200 (application/json)
    + Attributes (object)
        + total: 100 (number, required) - Total number of users
        + page: 1 (number, required) - Current page
        + limit: 20 (number, required) - Items per page
        + data (array, optional)
            + (object)
                + id: 123 (number, required) - User ID
                + name: `John Doe` (string, required) - Full name
                + email: `john@example.com` (string, required) - Email address
                + age: 25 (number, optional) - Age in years
                + created_at: `2023-10-01T10:00:00Z` (string, required) - Creation timestamp

+ Response 201 (application/json)
    + Attributes (object)        
        + id: 123 (number, required) - User ID

+ Response 422 (application/json)
    + Attributes (object)
        + message: "Validation failed" (string, required) - Message
        + details (array, optional) - Validation errors
            + (object)
                + field: "email" (string, required) - Field name
                + error: "Invalid email format" (string, required) - Error message
            + (object)
                + field: "name" (string, required) - Field name
                + error: "Name is required" (string, required) - Error messageShow more lines

Organizing Documentation into Multiple Files: Divide and Conquer for Large Projects

When your API grows to dozens of endpoints, stuffing everything into a single index.apib file becomes a nightmare. Imagine a 2000-line file covering everything from authentication to payment — searching and editing becomes time-consuming. This is when you should apply the “divide and conquer” principle.

Why Split Files?

API Blueprint supports an include mechanism that allows you to split a large file into smaller ones, each focusing on a specific functionality. The benefits are clear:

Easier to read: Each file is short and focused.
Easier to review: Pull requests only affect relevant files, making reviews more efficient.
Fewer conflicts: Multiple people can work in parallel without stepping on each other.
Scales well: Adding new modules only requires creating a new file and including it.

How Include Works

API Blueprint uses HTML-style comments to “call” other files into the main file. Aglio understands this syntax:

Shellapib isn’t fully supported. Syntax highlighting is based on Shell.
Show more lines

When it encounters this line, the tool automatically “copy-pastes” the content of the specified file into that position — similar to #include in C/C++ or import in JavaScript.

Example:

FORMAT: 1A
HOST: https://api.yourcompany.com/v1

# Order system API documentation
* This is the API documentation for the **order management system**
* Last updated: **2025/10/03 10:00:00**

# Group user
<!-- include(user/userSearch.apib) -->
<!-- include(user/userCreate.apib) -->

## userById [/users/{id}]
<!-- include(user/userGetById.apib) -->
<!-- include(user/userUpdate.apib) -->
<!-- include(user/userDelete.apib) -->

Suggested Folder Structure

my-api-documentation/
├── bin/
│   ├── intro/
│   │   └── overview.apib
│   ├── common/
│   │   ├── instruction.apib
│   │   ├── commonSearchSpec.apib
│   │   ├── validation.apib
│   │   ├── errors.apib
│   │   └── pagination.apib
│   ├── auth/
│   │   ├── login.apib
│   │   └── logout.apib
│   ├── user/
│   │   ├── userSearch.apib
│   │   ├── userCreate.apib
│   │   ├── userUpdate.apib
│   │   ├── userLock.apib
│   │   ├── userUnlock.apib
│   │   └── userDelete.apib
│   ├── orders/
│   │   ├── orderSearch.apib
│   │   ├── orderCreate.apib
│   │   ├── ...
│   │   └── orderDelete.apib
├── index.apib
└── index.html

Optimizing Workflow with Automation

Once you’ve mastered file organization, the next step is to optimize your workflow to save time and reduce errors.

Auto Build and Watch Script

Instead of running aglio -i index.apib -o index.html manually every time you make a change, you can create an automated script using package.json:

{
  "name": "my-api-documentation",
  "version": "1.0.0",
  "scripts": {
    "build": "aglio -i index.apib -o index.html"
  },
  "devDependencies": {
    "aglio": "^2.3.0"
  }
}

Now you can simply run:

npm run build

Instead of typing the full aglio command every time!

Conclusion: From Blueprint to Professional Documentation

After a long journey — understanding the problem, setting up the environment, mastering the syntax, and optimizing the workflow — you now have a powerful “weapon” to create high-quality API documentation. What makes API Blueprint special is not just its simplicity and ease of learning, but also its ability to scale smoothly from small projects to enterprise-level systems.

Key Takeaways

Start simple, scale gradually: You don’t need to be perfect from the beginning. Start with a basic index.apib file and a few endpoints, then gradually refactor into a multi-file structure as the project grows. This is the strength of API Blueprint — it doesn’t force you into a bulky framework from the start.

Documentation as Code: Treat API documentation as part of your codebase, not a “side task.” When the API changes, the documentation should be updated in the same pull request. This ensures the documentation stays in sync with reality and becomes the single source of truth.

Automate everything possible: From syntax validation, HTML build, to deployment and team notifications — the time you invest in setting up automation will pay off many times over during maintenance and future development.

Most importantly, remember that good documentation isn’t just about correct syntax or a pretty interface — it’s about creating a great experience for those using your API. Every time you write a description, ask yourself:
“If I were a new developer, would I clearly understand how to use this API?”

API Blueprint vs OpenAPI/Swagger: Which Tool Should You Choose?

Of course, in the world of API documentation, API Blueprint isn’t the only option. OpenAPI (formerly Swagger) is also a major player with a vast ecosystem and trusted by many enterprises. So when should you choose API Blueprint, and when should you lean toward OpenAPI?

API Blueprint is a great choice if you’re working in a small team and need to create documentation quickly. Its simplicity and readability shine when human understanding is the top priority. If your API is relatively simple and doesn’t involve deeply nested data structures, API Blueprint is the perfect “sword.” Especially if your team is already familiar with Markdown-style documentation, API Blueprint integrates smoothly without changing existing habits.

OpenAPI/Swagger is more suitable when you need a large ecosystem of tools — from auto-generating client code to advanced testing utilities. If your API has complex structures with many nested schemas, or you’re working in a large enterprise environment that requires professional tooling, OpenAPI will serve you better. And if your team is already comfortable with JSON/YAML formats, transitioning to OpenAPI will be seamless.

Why Do We Need API Documentation?

API Blueprint and aglio – The Perfect Solution for API Documentation

Why is API Blueprint + aglio so effective?

Setting Up the Environment

Step 1: Install Node.js

Step 2: Install aglio

Step 3: Quick Start with a Prebuilt Template

Structure of an API Blueprint

◆ Header and Metadata (optional)

◆ Group

◆ Resource (optional)

◆ API Specification

Input Description

◇ If using Parameters:

◇ If using Request:

Output Description

Organizing Documentation into Multiple Files: Divide and Conquer for Large Projects

Why Split Files?

How Include Works

Suggested Folder Structure

Optimizing Workflow with Automation

Auto Build and Watch Script

Conclusion: From Blueprint to Professional Documentation

Key Takeaways

API Blueprint vs OpenAPI/Swagger: Which Tool Should You Choose?

◇　If using Parameters:

◇　If using Request: