For the last 2 days I have been struggling with a breaking change I had in my ASP.NET Core web api that caused the consuming application to fail. I had a header parameter that was optional but became required after changing the nullability of my project to enabled . Although I found the issue and was able to fix it quite fast, I was not happy with my current process and was wondering how I could prevent this from happening again. This brought me to a final solution where I introduced some extra tests that compared the OpenAPI metadata between different implementations. Let me show you how I did it… Generate OpenAPI documents at build time To compare 2 OpenAPI metadata documents we first need to get them. For the already released version of the API, I can download the document through the OpenAPI endpoint ( /openapi/v1.json by default). But what about the new version of the API that is still in development? I solve this by generating the OpenAPI document at build time. This m...
Yesterday I talked about a breaking change I had inside my ASP.NET Core web api that caused my application to fail. I had a header parameter that was optional but became required after changing the nullability of my project to enabled . My hope was that this would be visible in the OpenAPI metadata for my OpenAPI. Unfortunately, the generated metadata always looked like this: So both this code: and this code: return exactly the same metadata. The lack of a required property marks this header as optional, which doesn't reflect the actual behavior of the application after enabling nullability. I decided to investigate this a little further and found out that it is possible to emit the correct metadata by explicitly adding a [Required] attribute to the parameter: After adding this attribute the metadata was updated correctly. It’s unfortunate that ASP.NET Core doesn’t do this by default as it is aware of the possible nullability of the provided parameters.