SwaggerHub: A collaborative platform for working on OpenAPI/Swagger specification files, and more

Summary: Listen to this post: You can download the MP3 file, subscribe in iTunes, or listen with Stitcher. A world standard for describing REST APIs Smartbear recently announced support for new OpenAPI 3.0 version of the spec in SwaggerHub. The 3.0 version of the OpenAPI spec provides a number of enhancements, such as providing support for callbacks, linking between operations, more robust properties with examples, and easier content re-use. You can read about OpenAPI’s 3.0 features here. (Note: Before continuing, I want to clarify a few terms for those who may be unfamiliar with the OpenAPI/Swagger landscape. “Smartbear” is the company that maintains and develops the open source Swagger tooling (Swagger Editor, Swagger UI, Swagger Codegen, and others). Smartbear formed the “OpenAPI Initiative” and leads the evolution of the “OpenAPI specification”. “SwaggerHub” was developed by Smartbear as a way for teams to collaborate around the OpenAPI specification file. “Swagger” was the original name of the spec, but it was changed to “OpenAPI” to reinforce the open, non-proprietary nature of the standard. People often refer to both names interchangeably, but “OpenAPI” is the preferred term. The Swagger YAML file that you create to describe your API is called either the “OpenAPI specification file” or the “OpenAPI contract.” Now that I’ve cleared up those terms, let’s continue.) I’ve written in the past about how Swagger-related posts are the most visited posts on my site. The OpenAPI/Swagger specification (instead of RAML or API Blueprint) continues to be the most dominant specification for describing REST APIs. In a recent webinar description about the OpenAPI 3.0 spec, Smartbear says OpenAPI “has emerged as the world’s standard for defining and describing RESTful APIs” — it would be hard to argue otherwise. Because of this emergence as the world standard, in my API course, I added a tutorial on OpenAPI/Swagger and another tutorial on Managing OpenAPI/Swagger Projects with SwaggerHub. Note: SwaggerHub is one of the sponsors of my site. Why OpenAPI is so popular What accounts for OpenAPI’s popularity and wide acceptance? I think the OpenAPI spec continues to be popular because it provides a standard in an area of technology that is a wild west of differing options, approaches, and terminology. Many technical writers who want to learn more about API documentation are overwhelmed by the breadth and diversity in this space. The challenge is not so much that there are new terms, new tools, and new documentation techniques to learn. The challenge is that there are so many conflicting terms, competing tools, and varying documentation techniques that unless you’re a maven with APIs, it’s hard to know the right path to follow. For example, what do you call all of your endpoints/methods/objects/resources/paths? How do you refer to the various types of path/query/body/head parameters? What template or pattern or arrangement do you follow in your API documentation to cover the various elements in the API reference as opposed to other non-reference API topics? Do you auto-generate the spec file from the code, or do you create the spec file manually? Do developers write the content, or do technical writers, or both? Where do you publish your API docs, and how do you integrate the information into your user guides and other help material? Documenting an API is like being dropped off in a busy, bustling city in another continent, without a map or idea of transportation, and without a clear idea of where you even need to go, just that you need to go somewhere, and do something. It can be overwhelming, because not only is the approach you should take in your documentation unclear, the developer-based nature of the content is often complex as well. When you discover the OpenAPI specification for describing REST APIs, you suddenly have a map and a direction. You have a language to describe it all. You have a documentation template to populate. You have an idea