After six years of investment in this space, I've decided to completely remove OpenAPI from the product. This is not a decision taken lightly. Despite eight previews, adoption remains low. But more importantly, I've come to realize that the ecosystem doesn't meet the quality standards our users have come to expect (and unlikely ever will).
Our goal from the start was to provide a working end-to-end experience. That involves not only generating the OpenAPI document, but also consuming it to run a documentation website and to send JSON:API requests from a generated typed .NET client (with automated end-to-end tests that cover all JSON:API features). To pull that off, we took a dependency on Swashbuckle server-side and NSwag/Kiota client-side. Swashbuckle itself depends on Microsoft.OpenAPI, which provides an object model and serializer for OpenAPI (not to be confused with Microsoft.AspNetCore.OpenApi, which doesn't provide the features we need).
Without going into details, these dependent open source projects generally suffer from:
- Maintainers come and go, with varying OpenAPI expertise and limited time/interest
- There is barely any test code, so breaks often go unnoticed
- While the bar for changes in some projects is very high, others release crappy community PRs without much consideration
- If you report a bug, you'll likely need to fix it yourself
The OpenAPI spec itself isn't great either. It is based on JSON Schema, which is a constraint-based language: a schema specifies what is not allowed. That doesn't work well for endpoints and data models, where the goal is to describe what is allowed. Due to this, many different constructs can be used to express the same data structure. The spec is hard to read, sometimes vague and often misunderstood. So readers look for fuzzy patterns to try to make sense of it, resulting in all kinds of incompatibilities.
As a result, I'm spending the majority of my time nowadays on upstream problems: creating minimal repros, while getting pulled into exhausting discussions. After fixing a bug, it was back a few months later. Someone else broke it again (and changed the tests I added). This happened more than once. I don't give up easily, but it feels like a never-ending story.
I'd rather spend my time enhancing the core product. Dropping OpenAPI enables me to get back to that.
After six years of investment in this space, I've decided to completely remove OpenAPI from the product. This is not a decision taken lightly. Despite eight previews, adoption remains low. But more importantly, I've come to realize that the ecosystem doesn't meet the quality standards our users have come to expect (and unlikely ever will).
Our goal from the start was to provide a working end-to-end experience. That involves not only generating the OpenAPI document, but also consuming it to run a documentation website and to send JSON:API requests from a generated typed .NET client (with automated end-to-end tests that cover all JSON:API features). To pull that off, we took a dependency on Swashbuckle server-side and NSwag/Kiota client-side. Swashbuckle itself depends on Microsoft.OpenAPI, which provides an object model and serializer for OpenAPI (not to be confused with Microsoft.AspNetCore.OpenApi, which doesn't provide the features we need).
Without going into details, these dependent open source projects generally suffer from:
The OpenAPI spec itself isn't great either. It is based on JSON Schema, which is a constraint-based language: a schema specifies what is not allowed. That doesn't work well for endpoints and data models, where the goal is to describe what is allowed. Due to this, many different constructs can be used to express the same data structure. The spec is hard to read, sometimes vague and often misunderstood. So readers look for fuzzy patterns to try to make sense of it, resulting in all kinds of incompatibilities.
As a result, I'm spending the majority of my time nowadays on upstream problems: creating minimal repros, while getting pulled into exhausting discussions. After fixing a bug, it was back a few months later. Someone else broke it again (and changed the tests I added). This happened more than once. I don't give up easily, but it feels like a never-ending story.
I'd rather spend my time enhancing the core product. Dropping OpenAPI enables me to get back to that.