New OpenAPI 3.0 specification tutorial in my API Course
You can view my OpenAPI 3.0 tutorial here: OpenAPI 3.0 tutorial overview. Here are the 8 steps in the tutorial:
- Step 1: openapi object
- Step 2: info object
- Step 3: servers object
- Step 4: paths object
- Step 5: components object
- Step 6: security object
- Step 7: tags object
- Step 8: externalDocs object
You can read the full OpenAPI specification here.
You can view the sample Swagger UI output from my OpenAPI specification document in a couple of ways:
Previously, I had some tutorials on Swagger, but none that dived into the nuts and bolts of creating a specification document.
Also, a lot has happened in the past year with Swagger. First, the terms have evolved. “Swagger” now refers to API tooling. “OpenAPI” refers to the specification. The development of the OpenAPI spec is led by the OpenAPI Initiative, not Smartbear.
Additionally, the OpenAPI Initiative released version 3.0 of the specification. Version 3.0 is a significant revision from 2.0 (but you can convert your existing spec files programmatically through APIMATIC). (I was actually waiting for the release of 3.0 before writing this content, because I knew instructions related to 2.0 would become somewhat obsolete.)
I had to go back through the whole section on REST specifications in my course and update how I referred to the specification versus the tooling. I also reorganized the content, added more detail, and tried to bring everything up to date.
Maintaining these tutorials on API documentation is certainly a challenge, since this space is rapidly evolving. In addition to the major changes from 2.0 to 3.0 in the specification, and the ownership and steering of the specification from Smartbear to the OpenAPI Initiative, Swagger UI (the display framework that reads the spec and generates an interactive documentation website) also updated to a new version (3.4).
With all these changes, I needed to overhaul the entire section on REST specifications and clarify terms. I even added an API Glossary to my API course.
Also, when I first put together the material on REST specifications, RAML and API Blueprint were also more serious contenders for widespread acceptance of the spec. But in the past couple of years, I’ve heard almost nothing about these other specs. I’m pretty sure they’re adoption continues to wane, and frankly, I don’t think we don’t need multiple specifications for REST. It’s confusing enough to learn one specification, let alone several, especially when they have the same goals and largely the same result.
If you’re working with a REST API project, I invite you to go through my OpenAPI tutorial and let me know if it’s helpful. (If so, consider adding a review.) Figuring out how to build the OpenAPI specification file from scratch can be somewhat daunting, and the specification documentation is more like reference documentation than anything else. It’s also constructed on one eternal page, so navigating it takes some getting used to. There are other tutorials online for building specification documents, but almost none that cover the newly released 3.0 version.
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.