Search results

Activity 4b: Edit an existing OpenAPI specification document

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 4b: Edit an existing OpenAPI specification document

Use this simple Sunrise and sunset times API to get more familiar with the process of creating an OpenAPI specification file. This Sunrise and sunset times API doesn’t require authentication with requests, so it removes some of the more complicated authentication workflows (the spec file doesn’t require the security object). In this activity, you’ll edit some of the existing values in an OpenAPI specification document that’s already written.

To edit the OpenAPI specification file:

  1. Copy the code from this pre-built OpenAPI specification.
  2. Paste the YAML content into the Swagger Editor.
  3. Identify each of the root-level objects of the OpenAPI spec:
  4. In the info object (near the top), make some changes to the description property and see how the visual display in the right column gets updated.
  5. In the parameters object, make some changes to one of the description properties and see how the visual editor gets updated.
  6. Look for the $ref pointer in the response object. Identify what it points to in components.
  7. Change some spacing in a way that makes the spec invalid (such as inserting a space before info), and look at the error that appears. Then revert the invalid space.
  8. Expand the Get section and click Try it out. Then click Execute and look at the response.
11% Complete

11/146 pages complete. Only 135 more pages to go.



Donate?

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