Here at Skookum we write a lot of REST services. REST services provides a great integration point between frontend and backend developers. This makes it easy to split work into large units, frontend development and backend development. Frontend developers write tremendously awesome user interfaces with clean markup and a performant and responsive user experience. Backend developers write testable, maintainable, performant, and robust service code.
The REST service specification is the glue that holds it all together. A specification allows frontend developers to start immediately by mocking the REST service responses with real data. A specification allows backend developers to start writing unit tests to ensure their code meets the desired state.
We all agree a REST service specification is a great tool to streamline and enhance our development process. We also all agree that writing documention is about as fun as a root canal. I have found a great tool to make this process easier--Swagger-UI. The Swagger set of tools is an entire toolset revolved around generating REST service documentation. At its core is the Swagger specification. Here is an example:
Swagger-UI is a tool that will transform the Swagger specification into a fully functional REST client that allows developers not only to view the REST documentation, but also interact with the REST API. You can view example requests, example responses, and even input arguments and see how the responses change. Overall its an awesome discovery tool and really helps developers, helping frontend developers learn an API, and helping backend developers for testing and demoing.
In our use of Swagger-UI, we came across one issue though. Swagger-UI is only good if users have access to the tool. If, however, you aren't able to put Swagger-UI in a public space, the users will not be able to view the documentation or interact with the API. For example, if you and your clients are on different networks, and the API should not be exposed on the public web. This leads you back to writing your own API documentation by hand again and losing the power of the Swagger specification.
Well, one handy thing about a specification is that—well, it's a specification. This means, as developers, we know it follows very specific rules. We can write tools that interact with that specification. So I decided to write a Swagger-to-Markdown script. This script can be found here https://github.com/Skookum/SwaggerToMarkdown/blob/master/swagger-to-markdown.rb. It takes a number of parameters, but the main parameters it takes is the Swagger specification for your API.
It will traverse your specification and generate a static Markdown file that contains a lot of the same information as the dynamic Swagger-UI tool. It writes out all the operations, their arguments, their error codes, and will even perform curl operations to generate example responses and example requests. Here is an example markdown file that was generated with our script.
See the results here.
Now we have another tool in our toolbox. For now, this script lives in one of our organization's repositories, but once I clean it up a little more I plan on giving it over to Wordnik. I hope others will find a use for this script.