Editing an OpenAPI Spec

Introduction

Editing an existing spec can be tedious and slow. If you're lucky enough to have a spec to begin with, it involves checking parameters and endpoints for accuracy, while also editing the descriptions.

Due to the format, it can be easy to get mixed up into rabbit hole after rabbit hole, causing you to forget where you started. When this happens, if you haven't prepared, you may end up editing the same lines of code over and over again.

This is the process I follow to edit quickly and avoiding unnecessarily reviewing the same lines multiple times.

Notes: This guide applies to OAS specs with the following limitations:

• OpenAPI 3.0

The Process

Step 1: Lint

Run the spec through a linter. I use Spectral. It will find obvious errors, such as examples that do not match their defined type. This is a great first step so that you're starting with a "clean" (free of mistakes) slate.

Step 2: Choose Endpoint to Edit

Unless your OAS spec is very small, it's generally best to work in batches. Choose an endpoint or set of endpoints to edit. Collect example responses from the API, by:

• Sending a test request to the API
• Getting the response from the Network tab on your browser
• Getting an example response from your SME

Step 3: Validate Example

Once you have example responses, you can validate the responses using the npm package openapi-examples-validator. This tool compares components in the spec to the example object you gathered in step 2. This is one of the most important steps because it doesn't matter how great your descriptions are, if your spec doesn't match what's actually happening, it's not useful.

Step 4: Add Fields

Comb through the endpoint(s) you are editing at this time and add the description and example keys, as needed. This applied to the

• endpoint
• parameters
• any sub-objects Leave both keys blank for now. I like to use the filler below, based on the object types:
• string: ""
• number: 111
• TK : add other types/fillers

Note: Using consistent fillers makes it easier to CTRL+F at the end to make sure you don't accidentally leave any blank descriptions or filler examples.

Step 5: Lint

Repeat Step 1. I do this after making any significant changes and stopping work for more than a few minutes of time.

Step 6: Write

Fill in missing descriptions and examples. Don't stop to look up information at this stage. Instead, use symbols to indicate that information is missing and needs to be looked up later.

If an object includes a $ref to another object, make a note and come back to it later. This helps you work systematically and avoid reviewing the same content multiple times.

Step 7: Review

Now it's time to fill in all the missing content you didn't fill in on the first round. This includes doing the following:

• Request information from your SME
• Search for each of the symbols above and adding the content
• Repeat step 1 and step 3
• Review and complete any client-specific steps that need to be followed

Step 8: Submit

Submit to your point of contact via PR, or their preferred method of review. Once they've had a a chance to review you may need to repeat some or all of these steps.

I've more than halved the time it takes me to edit an OpenAPI spec by following the steps above. Feel free to reach out if you have feedback or questions, or free consultation if you'd like to see if we'd make a good fit!

Symbols

• Don't stop writing to look up information.
• Fill in as much as possible, to the best of your knowledge. for any gaps in your knowledge use the following symbols:
  • TK: Information that you have access to but don't know off the top of your head. (From the copywriting shorthand for 'To Come'.)
  • TK@: Information that you'll need to ask a SME about
  • TK???: Information you think is correct but need to double check
  • RC: Mark a component that seems to be reused more than a few times, to potentially be reused
  • &: Parameters that seem to exist in the docs but not in the API.
    • This symbol goes on the inside of the object key (Meaning you can search for &" when editing.)
  • *: Parameters that are required in the API. This is helpful since parameters are marked as required in a separate array in request body objects.
    • This symbol goes on the inside of the object key (Meaning you can search for *" when editing.)

Checklist

The following is the checklist version of the list above.

1. Lint
   1. Run the spec through Spectral
      1. Fix any errors.
   2. If there are errors that cannot be addressed now, update the rules in .spectral.json.
2. Validate Examples
   1. Get example objects
   2. Add to directory
   3. Compare using the openapi-examples-validator package.
3. Skim
   1. Quickly get familiar with the spec.
   2. Mark components that may be reusable with RC
      • Do not make any changes yet.
   3. Reuse components where possible.
4. Add Fields
   1. Add the description and example keys to each object that you are editing at this time.
   2. Leave them blank for now:
      1. Type string = ""
      2. Type number = 111
5. Lint
   1. Run the spec through spectral and fix any errors.
   2. (Repeat this step throughout this process.)
6. Write
   1. Fill in descriptions and examples. You can do this by:
      • Viewing example objects, or
      • Using the client's API and observing how it works.
      • Don't stop writing to look up information or check external references. Use symbols to look up later
7. Lint
   1. Run the spec through spectral and fix any errors.
8. Indicate all required parameters
   1. Do this by reviewing the UI, or getting help from an SME.
9. Review
   1. Search for all the symbols above (TK, @, ???, &, and *) and fill in information
   2. Review any additional instructions from the Jira
10. Compare
    1. Get example objects from the client's API.
    2. Use the openapi-examples-validator package to compare the example objects with the spec.
    3. Make any necessary revisions
11. Submit for review
    1. Submit a pull request, using the process outlined by the client.