I’m finishing up the Swagger UI implementation for my REST API docs. I’ve already written a bit about Swagger previously (see my realizations post and single sourcing the spec post, as well as my Swagger tutorial).
In this post, I just want to emphasize how cool Swagger is, and why I think every REST API doc set should have one.
A few weeks ago I met with one of our field engineers as our product manager provided some training on the new release. Although the meeting lasted only about 30 minutes, one behavior was clear: the field engineer wanted to try out the requests during the training.
Most users want to do the same thing. They want to try out the product, whether it’s an API, software interface, or hardware product. The ability to push the buttons yourself is huge when it comes to learning.
Based on this experience, I decided to implement Swagger UI as a getting started tutorial for our API. This would allow users to easily input some sample parameter values and try out the requests and see the responses. Getting this all set up required the following:
Now that I’ve got everything set up, I really love it. I love having a sandbox space where users can try out requests, see responses, read briefly about the required parameters, and more. They can see the shape of the API and get a sense of what it returns.
I highly recommend describing in your REST API with the Swagger spec. This kind of sandbox/experimental space where users can try it out should be a part of every REST API documentation set.
Get new posts delivered straight to your inbox.
I'm a technical writer based in the California San Francisco Bay area. Topics I write about on this blog include technical writing, authoring and publishing tools, API documentation, tech comm trends, visual communication, technical writing career advice, information architecture and findability, developer documentation, and more. If you're a professional or aspiring technical writer, be sure to subscribe to email updates using the form above. You can learn more about me here.