Swagger 101

If you're involved with building, consuming, or testing REST APIs, you're probably familiar with Swagger. So what is it, and what can we do with it?

Swagger Specification

The Swagger Specification was originally created by SoftBear Software and is a specification format used to describe REST APIs.

The specification allows the author to describe REST API characteristics such as endpoints, authentication methods, valid actions, parameters, and expected responses, in YAML or JSON format.

The specification was rebranded as the "OpenAPI Specification" when it was donated by SmartBear to the open-source community in 2015. It is is now overseen by the OpenAPI Initiative. Most people I know still call it the "Swagger spec".

You can learn more about the OpenAPI Specification here.

Swagger Software

Swagger software is an open-source toolkit that is focused on the OpenAPI Specification and can be used to build, consume, and test APIs.

The Swagger Editor is a browser-based editor where you can create or edit an OpenAPI specification document.

Swagger Inspector is a browser-based tool which can be used to generate an OpenAPI spec for an existing REST API.

The Swagger UI can leverage an existing OpenAPI specification document to present a user interface that can be used to visualize and interact with the API.

Swagger Codegen can leverage an existing OpenAPI specification document to create server stubs, client libraries, and documentation.

What's the value?

Everything Swagger-related starts and ends with the Swagger spec. Once created, the spec has a number of uses:

• as documentation of API behavior, valuable to developers, testers, and API consumers
• as input to Swagger UI, allowing consumers to interact with the API through the browser
• as input to 3rd party tools used to generate client libraries and server stubs
• as input to 3rd party test automation tools that allow API tests to be automatically generated based on expected behavior defines in the specification

What's next?

Of course, this is just a basic overview of some Swagger concepts. In my next post I plan to look at how we can leverage the Swagger spec to generate automated API tests.

These automated tests can immediately let us know if the API does not conform to its spec.

Stay tuned!