In this course, I’ve emphasized using Swagger UI to parse and display the OpenAPI specification as interactive documentation. However, there are many other tools that can read OpenAPI specification documents. That’s the whole idea of a standard — when you create a standard way of describing APIs, many tools can predictably read the description and generate documentation (and other tooling) based on it.
Below I’ll expand on a couple of others, and add more over time.
I’m currently developing out the content here. Currently, the list tools and info is anemic.
Spectacle is an open-source Github project that builds an output from an OpenAPI specification file. The display provides a three-pane output similar to the Stripe or Slate docs. After you download the project files, you can build the display using Node simply by referencing your OpenAPI spec file.
Here’s a demo output.
You can also see an output that uses the Mashape weather API file.
With almost no needed setup or configuration, Spectacle gives you a world-class output and site for your API docs. As long as the OpenAPI spec that you integrate is fully detailed, the generated Spectacle site will be attractive and full-featured.
You can also build the Spectacle site without the framed layout so you can embed it into another site. However, in playing with this embed option, I found that to do this, I’d have to create my own styles. If using the default styles in the full-site output, they most likely will overwrite or interfere with your host site’s appearance.
Postman is a REST API GUI client that we explored earlier in Submit requests through Postman . The Run in Postman button provides a button (labeled “Run in Postman”) that, when clicked, imports your API info into Postman so users can run calls using the Postman client. As such, this isn’t a full-fledged authoring tool but rather a way to import the interactive, try-it-out API explorer for your endpoints into a web page.
You can see the many demos of Run in Postman here.
Here’s a demo of Run in Postman using the sample Mashape weather API:
Postman provides a powerful REST API client that many developers are familiar with. It allows users to customize the API key and parameters and save those values. Although you don’t have the in-browser experience to try out calls, in many ways the Postman client is more useful. This is what developers often use to save and store API calls as they test and explore the functionality.
Especially if your users are already familiar with Postman, Run in Postman is a good option to provide (especially as one option of many for users to try out your API), as it allows users to easily integrate your API into a client they can use. It gives them a jumping off point where they can build on your information to create more detailed and customized calls.
If you don’t already have a “Try it out” feature in your docs, the Run in Postman button gives you this interactivity in an easy way, without requiring you to sacrifice the single source of truth for your docs.
The downside is that your parameter and endpoint descriptions don’t get pulled into Postman. Additionally, if users are unfamiliar with Postman, they may struggle a bit to understand how to use it. In contrast, the “Try it out” editors that run directly in the browser tend to be more straightforward and do a better job integrating documentation.
Design your API through a GUI. The outputs are downloadable Open API 2.0 compliant documents. Use Open API 2.0 documents with Swagger tools to ease the creation of API mock, documentation and client SDK.
73/94 pages complete. Only 21 more pages to go...
If you would like to contribute back to say thank you for the API documentation course, click the Donate button below. Alternatively, to contribute content, such as a tutorial or a new section, contact me with your ideas. You can also submit a pull request in the GitHub repo to make your contribution. Even if you want to just fix a typo or add a sentence here and there, it's always welcome.
Get new posts delivered straight to your inbox.
© 2017, Tom Johnson