OpenAPI examples are like comments

For projects involving a lot of integration I recommend to use the specification-first approach, starting with an OpenAPI document and generating implementation code stubs (e.g. in Java) from it because in my opinion it brings a better separation of the implementation from the specification and helps in the API maintenance. (See my blog post) However, there are certainly things that can be improved in the OpenAPI specification itself and even more in the supporting tools. One such thing is the support for examples embedded in an OpenAPI specification. They are not mandatory, but including them will help both humans and automated test tools in understanding the data expected on the API. Unfortunately, the OpenAPI specification says that the examples "should" match the schema, so it is not required for them to be valid. This means they are like comments in any language, whose syntax is not checked. This is unfortunate because if someone changes a schema, it is easy for them to forget to make the respective changes in the examples. Outdated examples can be misleading. To prevent the situation, you can use a tool that validates the examples.

Jun 16, 2025 - 12:50

For projects involving a lot of integration I recommend to use the specification-first approach, starting with an OpenAPI document and generating implementation code stubs (e.g. in Java) from it because in my opinion it brings a better separation of the implementation from the specification and helps in the API maintenance. (See my blog post)

However, there are certainly things that can be improved in the OpenAPI specification itself and even more in the supporting tools. One such thing is the support for examples embedded in an OpenAPI specification. They are not mandatory, but including them will help both humans and automated test tools in understanding the data expected on the API.

Unfortunately, the OpenAPI specification says that the examples "should" match the schema, so it is not required for them to be valid. This means they are like comments in any language, whose syntax is not checked.

This is unfortunate because if someone changes a schema, it is easy for them to forget to make the respective changes in the examples. Outdated examples can be misleading. To prevent the situation, you can use a tool that validates the examples.