Adobe FrameMaker

Get new posts delivered straight to your inbox.

Subscriber count: 4,300

Stitcher radio

Adobe FrameMaker

New OpenAPI 3.0 specification tutorial in my API Course

Nov 7, 2017 • api-doc

I added a new tutorial on creating an OpenAPI 3.0 specification document in my API course. (OpenAPI was formerly referred to as Swagger.) The tutorial has 8 steps and guides you through the process of creating the specification document in the context of a sample weather API. Additionally, I explain how the specification fields get displayed in Swagger UI. Swagger UI is the display framework that reads the OpenAPI spec and generates an interactive documentation website.

You can view my OpenAPI 3.0 tutorial here: OpenAPI 3.0 tutorial overview. Here are the 8 steps in the tutorial:

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.

follow us in feedly

Get new posts delivered straight to your inbox.

Subscriber count: 4,300

About Tom Johnson

Tom Johnson

I'm a technical writer based in the California San Francisco Bay area. Topics I write about on this blog include the following technical communication topics: Swagger, agile, trends, learning, plain language, quick reference guides, tech comm careers, and certificate programs. I'm interested in information design, API documentation, visual communication, information architecture and findability, 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. You can also contact me with questions.