API Doc for a Symfony Project
Keeping your projects documented is very important. Everyone want to have it, but it must be simple, efficient and well maintained.
API Blueprint is another specification for describing REST APIs. It written in a Markdown-flavored syntax, but not exactly. It’s based on on the element names, order, spacing, and other details. If you describe your API with API Blueprint, you will find a lot of tools that support it.
API Blueprint is simple and accessible to everybody involved in the API lifecycle. Its syntax is concise yet expressive. With API Blueprint you can quickly design and prototype APIs to be created or document and test already deployed mission-critical APIs.
The API Blueprint ecosystem is very big, there’re plenty of tools in every language. Have a look to their “Tools” section.
Using Snowboard !
Snowboard (https://github.com/bukalapak/snowboard) is an awesome GoLang project to render HTML documentation from API blueprint file. It support custom templates and is an executable (or available as a Golang library). Could be integrate in your CI process or used directly with their Docker image.
One of the great feature provided by Snowboard is the ability to define the template used for HTML rendering. If your using Bootstrap (the front-end component library), you can generate it using an accordion and list group for menus. You can use it from my gist: https://gist.github.com/ScullWM/776ded66a812bdf28e05c93be48c21df
Now that we have our custom HTML template, we can include it in our application using Twig.
And here’s our beautiful API Doc integrated in our application:
Here was my small tip about API Doc in my Symfony project. Now share yours!
