Search results

Activity 4a: Explore Swagger UI through the Petstore Demo

Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 5,000+ subscribers

I'm giving an API documentation workshop in San Francisco, California, on November 19, 2019. Check it out on EventBrite and register today to receive a $100 early bird discount.

Activity 4a: Explore Swagger UI through the Petstore Demo

Let’s get some hands-on experience with Swagger UI using the Petstore demo. The Petstore demo provides a good example of how the OpenAPI specification can be rendered visually.

  1. Go to the Swagger Pet Store Demo.

    As with most Swagger-based outputs, Swagger UI provides a “Try it out” button. To make it work, you must first authorize Swagger by clicking Authorize and entering your API key in the Authorization modal. However, the Petstore authorization modal is just for demo purposes. There isn’t any real code authorizing those requests, so you can close the Authorization modal or skip it altogether.

    Authorization modal in Swagger UI
    Authorization modal in Swagger UI
  2. Expand the Pet endpoint.
  3. Click Try it out.

    Try it out button in Swagger UI
    Try it out button in Swagger UI

    After you click Try it out, the example value in the Request Body field becomes editable.

  4. In the example value, change the first id value to a unique (and unlikely repeated) whole number. Change the name doggie to a pet name you can remember (e.g., Bentley).
  5. Click Execute.

    Executing a sample Petstore request
    Executing a sample Petstore request

    Swagger UI submits the request and shows the curl that was submitted. For example, here’s the curl Swagger UI sent:

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

    Notice that, with the -d (data) parameter, the request body parameter is escaped and added directly into the curl command rather than being loaded from a file (as explained in Common curl commands related to REST).

    The Responses section in Swagger UI shows the response from the server. By default, the response returns XML:

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
      <Pet>
        <category>
          <id>0</id>
          <name>string</name>
        </category>
        <id>1000</id>
        <name>Bentley</name>
        <photoUrls>
          <photoUrl>string</photoUrl>
        </photoUrls>
        <status>available</status>
        <tags>
          <tag>
            <id>0</id>
            <name>string</name>
          </tag>
        </tags>
      </Pet>
    

    If you select JSON rather than XML in the “Response content type” drop-down box, you can specify that JSON is returned rather than XML.

    Response from Swagger Petstore get pet request

  6. The Petstore is a functioning API, and you have actually created a pet. For fun, expand the GET /pet/{petId} endpoint, click Try it out, enter the pet id you used in the previous operation, and then execute the request. You should see your pet’s name returned.
14% Complete

14/146 pages complete. Only 132 more pages to go.



Donate?

Want to buy me lunch? Click the Donate button below to donate any amount through Paypal.