Swagger Editor: My Favorite Features

I learned about Swagger recently when my boss told me to use it when designing a new API. At first, I was a bit skeptical since my approach was to take an agile and YAGNI approach and build the API bottom-up, basically add an endpoint as needed.

After using Swagger for a little bit, wow, Swagger is definitely a tool everyone working with APIs should have knowledge of, if not using!

There are different parts to Swagger, but in this article, I will go over the Swagger Editor and two of my favorite features: Try It Out and Response Format.

Why are they my favorite? Because these features answer a question I have about every API (even my own!)

• How do I make a request?
• What does the response look like?

An API is a backend developer’s GUI. :-)

Quick Overview of Swagger Editor

The Swagger Editor loads up an example API, the Pet Store API. (Doesn’t every Pet Store needs a full featured backend server to power it?!)

Here’s what the editor looks like:

Major parts:

• The left panel is the YAML description of the API.
• The right panel is the actual documentation generated from it.
• The top menu bar has options to open/save previous versions and create clients/servers.

This is the basics. You can try out things on both left and right panels. I will focus on how things work outisde of the left panel in this article.

Endpoint Details

The right panel has all the endpoints in colored sections described in the left panel.

By clicking on any one of the sections, the endpoint details expand further, revealing: Try It Out and Response Format.

Try It Out Button

This button is one of my favorite features of Swagger Editor. It gives an interactive format to fill in any options the endpoint may have and also generates a working curl command for you to try out.

To get to the Try It Out button: from the right panel, click on one of the colored bars, like the green one for POST /pet.

This button is amazing, when clicked on, another section opens up and provides a section to input different request parameters.

After modifying the parameters, click on the Execute button. This creates a curl request based on the request parameters that will work against the API!

This command:

$ curl -X POST "https://petstore.swagger.io/v2/pet" -H  "accept: application/json" -H  "Content-Type: application/json" -d "{  \"id\": 0,  \"category\": {    \"id\": 0,    \"name\": \"string\"  },  \"name\": \"doggie\",  \"photoUrls\": [    \"string\"  ],  \"tags\": [    {      \"id\": 0,      \"name\": \"string\"    }  ],  \"status\": \"available\"}"

Will work right from your computer. You can test out the API with just this command and it will return a response.

Response Format

The second favorite feature of Swagger Editor is: Response Format. This section of the documentation describes what’s in and the shape of the response from the server.

To find the response format details, scroll down further on the right panel, you can see what the above test request will send back as its response. The shape, basic values, etc.

This tells me what the server wil send back when I make a request. Included information and its structure. For the POST /pet endpoint, the response that comes back will be:

{
  "id": 8254402708133989000,
  "category": {
    "id": 0,
    "name": "string"
  },
  "name": "doggie",
  "photoUrls": [
    "string"
  ],
  "tags": [
    {
      "id": 0,
      "name": "string"
    }
  ],
  "status": "available"
}

Isn’t that cool?? Now I know what kind of response to expect from the server when I make the above API call.

Conclusion

I’ve just touched on two of my favorite features of the Swagger Editor: Try It Out and Response Format. The reason why these are my favorite is that they conclusively answer any question about the API:

• How do I make a request?
• What does the response look like?

The fact that Swagger Editor is interactive gives me absolute confidence that the answers given will work.

Getting to the answers for these questions are trivial, they are in the right panel of the Swagger Editor, under the Try It Out section and the Response Format.

Having an API documented interactively with Swagger just makes working with it a breeze.

(If you are a developer advocate or developer evangelist, having Swagger as part of your API is a gigantic competitive advantage at any hackathon!)