Common Mistakes Developers Make In Their OpenAPI 3 Files

OpenAPI 3 (OAS 3) is the latest iteration of the OpenAPI Specification. APIMatic has been supporting the format since it was still a release candidate. With adoption rates for OAS 3 going up, we noticed a few common mistakes developers are prone to make. Majority of these relate to the way certain features worked with OAS 2.0 (more commonly known as Swagger 2.0) but require a different approach with OAS 3.

Using the old “swagger” property to specify OpenAPI version

A Swagger user, who has had his hands dirty with version 2.0, would usually specify Swagger version using the swagger property as follows:

When migrating towards OAS 3, developers are still seen using the same property to specify the version of the newer format.

This is invalid as OAS 3 has now replaced that with the new openapi property which makes use of semantic versioning.

Defining body parameter in the “parameters”

Remember how Swagger 2.0 let you define a body parameter in the operation parameters using location set to body? Compared to parameters located elsewhere (query, header, path, formData), this parameter had less restrictions and used a schema object for type definition. OAS 3 decided to separate this parameter for good and let it have its own place in requestBody. The form parameters are also covered under this new property. But developers are still bent on defining the body parameter in the parameters section. Sigh.

This is now invalid in OAS 3:

The correct way is to instead use requestBody for form and body parameters:

Declaring response headers as a list of Header objects

It looks like some developers are trying to generate their OAS 3 files from 3rd party tools that do not fully conform to the OAS standards. This results in inaccurate header objects. The specification states that the response headers must be:

1) A map with header name as key and Header object as value OR

2) A map with header name as key and a Reference object as value (that basically would still point to a Header object).

This implies that an array of header objects or an array of reference header objects can, therefore, not be used but the mistake is still seen quite commonly. Also, the Swagger editor itself does not seem to complain in either case.

So essentially this is invalid (at least as per the spec):

The valid way is to use a map instead:

"responses": {
   "200": {
      "description": "Response for content that consists of a single part.",
     "headers": {
       "HeaderName": {
          "$ref": "#/components/headers/HeaderName"
        }
     }
  }
}

Referencing an undefined OAS 3 component

Last but not the least, developers often reference an OAS 3 component (definition of a schema, parameter, response, header or a security scheme, etc.) but they don’t define this component in the relevant section of the root components object. So for example, an OAS 3 response in the API file may be referencing a schema definition like:

This requires a definition for pet to be present under the schemas property that itself would lie inside the root componentsproperty as follows:

"components": {
   "schemas": {
      "pet": {
         "type": "object",
         "properties": {
           "propertyName": {
              "type": "string"
            }
          }
       }
    }
}

A lot of users forget to define some of these referenced components. Do ensure that any such references you make to components using $ref are resolvable to avoid issues with tools that use this format.

Conclusion

As of date, there is no official JSON schema available for OAS 3. With the release of JSON schema, we can expect better validation of OAS 3 files, which will ultimately lead to OAS 3 tools and services becoming more stable and consistent. It’s only then that the probability of such mistakes occurring will decline.

Have OAS files of your own? Head over to Transformer and start converting to other formats.