Swagger UI probably the coolest thing I've done in API docs
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:
- Have developers enable CORS on our API (this is necessary to make requests from Swagger).
- Describe the API in the Swagger specification.
- Create getting started tutorials for each of the endpoints.
- Set up a test environment with a sample configuration.
- Brand the Swagger UI display.
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.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.