From the course: Building APIs with Swagger and the OpenAPI Specification

Swagger ecosystem - REST Tutorial

From the course: Building APIs with Swagger and the OpenAPI Specification

Start my 1-month free trial Buy for my team

Swagger ecosystem

“

- [Instructor] To kick things off, we'll discuss the overarching concepts that build the Swagger platform's foundation. To effectively use Swagger, you must understand the high level difference between Swagger and the OpenAPI Specification. It's a little confusing and developers often have trouble understanding the difference. Swagger is a toolset and structured approach that helps us design, document and generate code for RESTful APIs. The OpenAPI Specification provides a standard format for creating metadata that defines RESTful web services. Knowing the history behind these projects can help us better distinguish between the two. Swagger began in 2010 when Tony Tam started an opensource project to provide interactive API documentation and client SDKs for APIs at Wordnik, an online dictionary service. At this point in its history, Swagger included both the specification and the tooling. The Swagger specification provided a structured approach for documenting APIs and you will hear it referred to as OpenAPI Specification 2.0 or Swagger docs. As time passed, Swagger gained popularity amongst several competing API description languages and what's acquired by SmartBear in 2015. In order to keep the specification vendor neutral, SmartBear donated the Swagger specification to the OpenAPI Initiative who renamed it the OpenAPI Specification. The OpenAPI Initiative is a collaborative working group focused on development of the OpenAPI Specification which was formerly the Swagger specification. Members of the OpenAPI Initiative include prominent organizations such as Microsoft, Google, IBM, PayPal and SmartBear. So it's important to remember that Swagger allows us to easily design, document and generate code for APIs. Swagger's toolset helps us produce API definitions that adhere to the OpenAPI standard. Other tools can read those definition files to build documentation, server stubs and other client SDKs that are useful for working with APIs. On the other hand, the OpenAPI Specification provides a standard format for metadata used to describe or define RESTful web services. The metadata is machine readable so it can be consumed by tools or systems that are built to understand API definitions adhering to the standard. So at high-level, think of Swagger as a set of tools and OAS as the rules for describing APIs. The Swagger Toolbox can be broken down into two categories, the open-source tools and pro tools. The open-source tools are available to be downloaded and installed for free use. These tools provide the basics that you will need to build an API definition, API documentation and client SDKs. The pro tools provide a more comprehensive platform that includes collaboration features for teams that are building APIs. Additionally, you'll find the tools to build API definitions, generate code and documentation within the pro tools. The pro tools are available via a subscription service which includes a free plan. So at a high-level, this is an overview of the Swagger ecosystem. At the top level of the hierarchy, we need to distinguish between the Swagger toolset and the OpenAPI Specification. The Swagger toolset is further categorized by the open-source tools and the pro tools. Throughout the course, we'll be diving into each of these areas, so that you can build higher quality APIs in less time.

Contents