Rendering your API Blueprint specification with Laravel
Last year, I published my first open-source package: Blueprint Docs, an API Blueprint Renderer for Laravel. It has reached 3k downloads and I’m happy to think that it might have served a couple of people.
Let’s have a quick look at API documentation in general, before I introduce the package.
Documenting your API
It’s a good idea to document your API. If it is public facing, there is no doubt about it. A thorough documentation is a prerequisite of a successful API service. But even if it’s an internal API, future you or other developers in your team might need to understand how it works. Having a documentation available is clearly better than digging through the code.
There are two parts to this: Documentation and Specification. The difference being that the documentation explains (human readable) how to use the API, while the specification nails down (machine readable) how it works and what to expect. However, you will find that these terms are often used interchangeably. I won’t bother much either.
Standards
Several standards exist that offer additional benefits over custom formats. For one, they are guides on what and how to specify all the parts that make up the request and response. More importantly though, an ecosystem of tools has emerged around these standards, offering linting, mocking and rendering of your specs.
The standard with the largest ecosystem and most widespread usage is OpenAPI, formerly known as Swagger. It offers great control but might be overkill for simpler APIs. I have enjoyed using API Blueprint in the past. It lacks some advanced features but its markdown based format is relatively easy to read and write. Check the official API Blueprint tutorials for a great introduction.
A simple request using the API Blueprint standard:
# GET /message
+ Response 200 (text/plain) Hello World!
The API Blueprint specification is written in a single file. There are tools that allow you to add your documentation in a DocBlock along-side your code but I prefer the one source of truth, no digging.
A quick tip
Consider specifying your API prior to implementing it, taking the time to streamline the user experience and to really think about the design of your interface first.
Details might change but there will be a clear path for development. Back-end and front-end developers could start working in parallel, taking advantage of mock-servers and automatic testing against the evolving implementation.
Blueprint Docs
A great feature of these specification formats is their ability to be parsed and rendered as accessible HTML documentation. Several renderers exist, format specific but agnostic to the programming language or framework of your implementation. The downside being that you need to manage a separate project for your docs. I wanted a solution that seemingly integrated with Laravel, my PHP framework of choice.
So, I wrote Blueprint Docs, an API Blueprint renderer for Laravel. No second server to spin up, no separate project. It’s simply a composer package that you pull in. It uses the same Laravel instance, your app is build on and renders your API Blueprint with its default theme, fully customizable via Blade.
The parser
The only requirement is Drafter, the official API Blueprint parser written in C++, which needs to be compiled on your machine beforehand. No worries though. Simply require the composer package Drafter Installer which takes care of Drafter’s installation process for you.
Installing Blueprint Docs
Once Drafter is installed, pull in the Blueprint Docs package:
Publish its assets to public/vendor/blueprintdocs:
Save your API Blueprint specification at the root of your project and find your rendered documentation at route /api-documentation.
If you haven’t written your own specification yet: Blueprint Docs includes the API Blueprint boilerplate. Publish this example to the root directory of your Laravel project:
Demo
If you are interested to see what the rendered API Blueprint looks like, check out this demo output for the API Blueprint boilerplate.
Theming
As I mentioned, you can fully customize the rendered documentation using Laravel’s templating language Blade. The default theme is just a starting point for making it your own.
To customize the default theme, publish its views to views/vendor/blueprintdocs:
I would love to see some custom designs in the wild. If you happen to have published a custom theme, let me know!
Embrace it
It feels quite rewarding seeing your API documentation in their rendered form. Make specifying your API a habit even for internal usage and try designing your API first, taking full advantage of the tools these standards bring along.
If you have any feedback regarding the package, please get in touch. You can find me on Twitter as @m165437.
