API Blueprint (APIB) is a language for describing client-server interactions with JSON payload. APIB allows developers to describe the format of server requests, server responses, URL parameters, and much more.
APIB uses Markdown syntax as a basis. To describe data structures in APIB documentation MSON syntax is used. With help of MSON, it is easy to define structures of requests and responses or to define named types and use them throughout the document.
A lot of companies across the world use JSON API in their projects, and so do we. API description is one of the essential tasks, which helps to support and develop projects that a large team is working on. That is why we felt a strong need for convenient tools to work with documentation.
Historically, the battle was between API Blueprint
and Swagger.
We chose API Blueprint for two reasons. Firstly, the source code of documentation
that is described using API Blueprint is more readable to humans.
Secondly, at the time of research conducted, Swagger lacked several important features,
as One Of support.
To start working with APIB documentation you need:
- A text editor — VS Code, Vim or any other. Enabling Markdown syntax highlighting can be useful.
- A tool to render a document to an HTML page.
- A tool to parse APIB documentation. In most cases, a parser is a part of a renderer, but sometimes you can use it explicitly to build other APIB utilities.
API Blueprint standard is mostly maintained by Apiary, which owns the official parser Drafter. Other enthusiasts help to develop some tools to work with API Blueprint, including renderers.
For some time a standard set of tools to work with APIB documentation had been including Drafter as a parser and aglio as a renderer.
Drafter is a great tool that had been helping us a lot with documentation, but it lacks some desired features like multi-file support or the ability to describe complex data types with JSON Schema.
We'd had a personal vision of the functionalities to implement, so we had built our own set of tools and utilities to work with APIB documentation. Our implementations are written in plain JavaScript, because we use this language a lot in our projects.
Crafter is an API Blueprint parser, heavily inspired by Drafter. Crafter is mostly compatible
with Drafter and supports the majority of its functionality, but our library offers additional features:
- Modules. Now it is possible to split one giant file into parts, which makes documentation easy to use.
- Resource Prototypes allow you to set up common responses in one place and reuse them through the documentation.
- Support of arrays in query strings.
- JSON Schema based types. In case of complex types it is possible to describe them directly as JSON Schema.
- String validation attributes that describe the expected length of parameters and regular expressions they should match.
- Describe a non-HTTP interaction (as WebSocket) by means of Message section.
- Extended sourcemaps. Crafter generates detailed sourcemaps for APIB elements, that allowed us to develop our own extension for VSCode.
Additional information about Crafter you can find in project README.
Blueprinter is an API Blueprint renderer. It uses source .apib documentation
to generate API AST in the form of API Elements and
create an HTML page with documentation.
Blueprinter advantages:
- Modern design. Dark theme included!
- Search support. You can search for groups, resources, and actions using provided search field. If the custom search field is not enough, you can use standard browser search on the special manual search page.
- Printer-friendly.
- Deep integration with APIB parser. Parsing errors and warnings are not swallowed but have pretty representation.
Here is an example of how a Blueprinter page looks like:
Additional information about Blueprinter you can find in project README.
APIB Language Server is a VS Code extension that allows to enhance developer experience when creating and editing API Blueprint documentation.
This extension brings you:
- Syntax highlighting.
- Diagnostic messages.
- Breadcrumbs of documentation sections.
- “Go to definition” implementation for data structures and resource prototypes.
- Autocomplete for types and structure names.
See demo of how the extension could be useful:
Additional information about how to install and use VS Code plugin you can find in project README.
API Validator is a frontend tool to validate server response against API Blueprint documentation.
To minimize the number of errors on the frontend side associated with incorrect backend responses, we developed a tool for automatic validation. It extracts JSON schema from the API Blueprint documentation and allows to automatically check correspondence between the backend response and the documentation for this request.
Additional information about how to use API Validator you can find in project README.
An API Blueprint documentation relies on two original specifications:
FunBox APIB tools introduce a lot of new features, described in the following specifications:
In these specifications, you can find out what sections the typical documentation consists of, and what rules you should follow when you work with the content of API Blueprint documentation.
- Dropped support of Resource model section and Relation section.
- Resource prototypes section definition was added. This allows you to set up common responses in one place and reuse them through the documentation.
- Import section definition was added. This allows to to split big documentation into several files.
- Definitions of SubGroup and Message sections were added. This allows to describe interactions that do not rely on massively beloved REST+HTTP, e.g. WebSocket messages or Apache Kafka messages.
- Schema Structures section definition was added. This allows to describe complex data structures directly in JSON Schema format.
- A few other non-significant improvements.
- New type attributes for a string value: format and pattern. See Type Attribute section. These attributes give you more precise control over the value validation within JSON Schema.
- New type attributes for an array value to specify array size:
min-lengthandmax-length. See Size Range section. - New type attributes
minimumandmaximumfor a numeric value to validate a number against the specified range of values. See Range Of Numbers section. - Removed definition of the fixed-type attribute for arrays.
- Described opportunity to define description of One Of elements.
- A few other non-significant improvements.
First, you need to install Node.js to work with APIB documentation. You can get it from the official site, via Homebrew (MacOS X) or a repository (Linux). Recommended Node.js version is 14.18.0 or higher.
In the root of your APIB project create package.json with the next content:
{
"name": "project-name-apib",
"version": "1.0.0",
"description": "API Blueprint documentation for the project 'Project Name'",
"scripts": {
"dev": "npx @funboxteam/blueprinter -i doc.apib -s -p 3000",
"doc": "npx @funboxteam/blueprinter -i doc.apib -o index.html"
},
"dependencies": {
"@funboxteam/blueprinter": "5.1.0"
}
}- In the
namesection, write the name of your project instead ofproject-name. Postfix-apibspecifies that this is a project for APIB documentation. - In the
descriptionsection, write your product name instead ofProject Name. - Specify the latest version
of
@funboxteam/blueprinterinstead of5.1.0.
When you're done with package.json, run npm install to install @funboxteam/blueprinter
as a dependency.
In your project root folder add the doc.apib file with documentation. If you use another file as an entry point,
replace doc.apib argument in dev and doc npm scripts with the corresponding path.
You can split documentation into separate parts and include them in the root file with the Import keyword.
Our implementation of the Import statement sets several restrictions on how a documentation
can be split into parts and how these parts can be imported into each other.
-
Imported APIB files must contain a standalone top-level APIB section. At this moment, the next sections are regarded as top-level:
-
All APIB file dependencies should be imported explicitly. You can not define data structures or resource prototypes in a separate file, import them in the root
doc.apibfile, and then implicitly use them in other imported files.Example.
Wrong APIB doc, where the file resources.apib uses data structures from data-structures.apib:
doc.apib
# My Doc # Import data-structures.apib # Import resources.apib
Correct APIB doc, where data structures are explicitly included in the file where they are used:
doc.apib
# My Doc # Import resources.apib
resources.apib
# Import data-structures.apib # GET /user + Response 200 + Attributes (User)
Examples folder contains available examples of common APIB cases.
If you spot a problem, want to offer some improvements or have a question, create a new issue in the project.
Logos for projects were made by Igor Garybaldi.
