The thoroughness of Tom Johnson's free Documenting API's course on OpenAPI 3.0 and Swagger UI

While researching information for my job about the Swagger UI and how it can be used for testing, I came across this free course, called Documenting APIs: A guide for technical writers and engineers at https://idratherbewriting.com/learnapidoc/docapis_overview.html written by Tom Johnson, a technical writer based in Seattle who works for Google. 

The course looks intense, containing 17 chapters talking about Introduction to REST APIs, using APIs like a developer, Documenting API endpoints, the Open API spec, Testing API docs, Publishing API docs, and more.

From the Course Introduction: "You’ll first learn about API documentation by using a simple weather API to put a weather forecast on your site. [...] As you use the API, you’ll learn about endpoints, parameters, data types, authentication, curl, JSON, the command line, Chrome’s Developer Console, JavaScript, and more. The idea is that rather than learning about these concepts independent of any context, you learn them by immersing yourself in a real scenario while using an API. Immersion in real scenarios makes these tools and technologies more meaningful.

"We’ll then transition into standards, tools, and specifications for REST APIs. You’ll learn about the required sections in API documentation, analyze examples of REST API documentation from various companies, learn how to join an open-source project to get experience, and more.

"[...] We’ll also dive into specifications such as the OpenAPI specification and Swagger UI (which provides tooling for the OpenAPI specification). Additionally, you’ll learn how to document native library APIs and generate Javadoc".

Tom Johnson offers a PDF version of this free course... over 900 pages, with more always being added. It also offers many workshop-like activities you could put in an actual itinerary.

You would need for the course: 

• Chrome, since it provides "a Javascript Console that works well for inspecting JSON", the JSON Formatter Chrome extension, Postman, a GitHub account, an OpenAPI editor such as Swagger Editor. 
• We would be using tools like Git, curl.
• The product under test would be the OpenWeatherMap API, so we would need to sign up to get an API Key from https://openweathermap.org/.

It also seems to offer the Video recordings of API doc workshops, and Course Slides for the links.

Working through the course, I found it very insightful, with Tom providing so many related links so you could really dive deep into a topic. 

• As it told the story of REST, it introduced SOAP API, explaining how it was too heavyweight, making it slower. It also introduced Dr. Roy Fielding who originated the Representational State Transfer architectural style in his disertation, Architectural Styles and the Design of Newwork-based Software Architecures, and co-founded the Apache HTTP Server project. 
• When talking about curl, it referenced the curl man pages at https://curl.se/docs/manpage.html. Tom then walked through how you could interact with the Swagger Petstore API to create a new pet, update the pet, get the pet's ID, delete the pet, then try to verify the pet was truly deleted. [Activity: Use methods with curl]
• When talking about using APIs like a developer, it instructed the reader how to use some autogenerated jQuery code from Postman to create an AJAX request, generate an API key from a service like OpenWeatherMap.org, then use that key to do things such as access specific information from an API using dot notation, and create a web page embedded with your local weather information such as wind speed and temperature.  [Activity: Inspect the JSON from the response payload]
• When introducing the parts of a REST API, mentioning how GraphQL is slightly different, it mentioned the API Evangelist's GraphQL and REST differences as explained with Burgers. 
• When introducing the OpenAPI spec, it mentions SmartBear's free API Documenting tool called Stoplight, pointing out some Stoplight: Getting Started tutorials (also created by Tom Johnson). 
• When talking about OpenAPI, Tom references There’s No Reason to Write OpenAPI By Hand by Phil Sturgeon and with Codegen, Tom mentions we should see Comparison of Automatic API Code Generation Tools For Swagger by Kin Lane, aka the API Evangelist and tools such as OpenAPI Generator ... all before an introducing a chapter on how to manually create the code, a best practice in the industry. "The main weakness of generating your OpenAPI spec from code is that the spec can no longer serve as the blueprint for creating the API, and instead becomes an afterthought".

It covers a lot of material such as:

• Five common sections in REST API docs: Resource description, Endpoints and Methods, Parameters, Request example, Response example and schema
• An Introduction to the OpenAPI spec, OpenAPI spec and generated reference docs contains a Swagger UI tutorial working with the Swagger Petstore. 
• Downloading Swagger UI and pointing it to another API such as the OpenWeatherMap API [Swagger UI Tutorial]

All of this is written from a technical writer's perspective. 

• About writing Quick Reference Guides describing APIs: "Quick reference guides are like the poetry of technical writing. The goal is not just to be brief or concise. With poetry, the poet attempts to evoke a mood or paint a moment, and in that brief moment, capture the essence of the whole".

He does make sure to give a shoutout to us software testers:

• REST API Doc Parameters: "When you test an API, try running an endpoint without the required parameters, or with the wrong parameters, or with values that exceed the max or min amounts. See what kind of error response comes back. Include that response in your status and error codes section. I talk more about the importance of testing in Testing your docs".

Thank you so much, Tom Johnson for this free course! 

Happy Testing!

-T.J. Maher
Software Engineer in Test

BlueSky | YouTube | LinkedIn | Articles