DEV Community

Cover image for Swagger 101
Dennis Whalen for Leading EDJE

Posted on

2

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!


Smart EDJE Image

API Trace View

How I Cut 22.3 Seconds Off an API Call with Sentry 🕒

Struggling with slow API calls? Dan Mindru walks through how he used Sentry's new Trace View feature to shave off 22.3 seconds from an API call.

Get a practical walkthrough of how to identify bottlenecks, split tasks into multiple parallel tasks, identify slow AI model calls, and more.

Read more →

Top comments (0)

Heroku

Simplify your DevOps and maximize your time.

Since 2007, Heroku has been the go-to platform for developers as it monitors uptime, performance, and infrastructure concerns, allowing you to focus on writing code.

Learn More

👋 Kindness is contagious

Discover a treasure trove of wisdom within this insightful piece, highly respected in the nurturing DEV Community enviroment. Developers, whether novice or expert, are encouraged to participate and add to our shared knowledge basin.

A simple "thank you" can illuminate someone's day. Express your appreciation in the comments section!

On DEV, sharing ideas smoothens our journey and strengthens our community ties. Learn something useful? Offering a quick thanks to the author is deeply appreciated.

Okay