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.

Testing the Swagger Petstore: Manually Testing An API Using Swagger UI

With the last post, Testing the Swagger Petstore: Reviewing API Documentation Formatted in OpenAPI 3.0 with Swagger UI we started exploring an API with Swagger UI, such as the Swagger Petstore at https://petstore3.swagger.io/

Here, we will start exploring how to test an API using the Swagger UI.

The tests we can run are:

• Happy Path Testing, checking the Positive Scenarios
• Negative Testing, reviewing the Invalid Inputs & Error Handling
• Boundary & Edge Case Testing, checking how the API handles the extreme limits of allowed input ranges
• Authentication & Authorization Testing
• Contract and schema validation

We can see in the Swagger PetStore there are three tag groups: Pet, Store, and User. 

Because this is a Swagger UI doc, we can perform manual testing using only the "Try it out" feature in Swagger UI. No external tools needed! Live HTTP requests can be executed directly from your browser.

Testing the Swagger Petstore: Reviewing API Documentation Formatted in OpenAPI 3.0 with Swagger UI

For this next project, we will be examining the test site Swagger Petstore - OpenAPI 3.0 at https://petstore3.swagger.io/

https://petstore3.swagger.io/

If we wanted to really dive deep into creating API documentation, we could use:

• I'dRatherBeWriting's Free Documenting APIs course, showing an Introduction to REST APIs, using APIs like a developer, Documenting API endpoints, the Open API spec, Testing API docs, Publishing API docs, and more... 

... But that goes too deep for this blog post. 

Before we begin, let's get into some background information. 

What is Swagger?

According to OpenAPISpec.com's article, Who Created Swagger?, Swagger was created in 2010 by Tony Tam, the CTO of Wordnik, an online dictionary company that leveraged so many APIs, it was difficult for the six person engineering team to manage and scale them, writing API-clients and documentation by hand. After a 3 AM conversation, they thought... what if the API documentation could describe itself?