Umbrella: OpenAPI integration

[maurei]

OpenAPI integration

This document provides an overview of the work items involved in creating an OpenAPI integration for JsonApiDotNetCore.

Disclaimer: this is an open source project. The available time of our contributors varies and therefore we do not plan release dates. This document expresses our current intent, which may change over time.

Approach

Creating an OpenAPI integration for JADNC requires setting up a mechanism that generates an OpenAPI Specification (OAS) file from application code. This file allows for automatic generation of API docs (see eg. SwaggerUI) and client code (see eg. NSwag code generator). In the design choices for this mechanism precedence will be given to compatibility with client code generation tools because we believe this to be of the biggest impact to the JSON:API community (see eg. this issue and others).

In a private repository we have experimented for several months with integrating Swashbuckles SwaggerGen in a JADNC application. We have decided to extract this code into this repository and move forward from there.

Work items

The order of the list below reflects the order in which we intend to address the work items.

• Improved isolation of tests #1031
• Minimal OpenApi integration #1047
• Import existing OpenApi integration #1048
• Use internal ResourceNameFormatter #1049
• Introduce a dedicated IApiRequestFormatMetadataProvider, removing the input formatter workaround #1050
• Generalized support for naming strategies in schema ids #1080
• Add support for handling of non-nullable reference types in required. #1111
• Support for XML doc-comments #1053
• Support for query string parameters #1058
• Support for top-level included object #1059
• Support for top-level jsonapi object #1061
• Member order in swagger.json #1115
• Generating multiple swagger documents is not supported #1233
• Support various JADNC controller types #1052
• Support for error responses #1057
• Add OpenApiEndToEndTests #1243
• Support for Kiota #1458
• Include HTTP headers #1367
• Set TopLevelLinks.DescribedBy to point to OpenAPI URL #1456
• Support for client-generated IDs #1054
• Generalized handling of link objects #1062
• Support for atomic operations #1060
• Reflect model state validation attributes in resource object schemas #1055
• Surface type hints in 'id' properties and parameters #1572
• Rename package to JsonApiDotNetCore.OpenApi.Swashbuckle #1578
• Reflect attribute/relationship capabilities in resource object schemas #1056
• Generalized handling of meta object #1063
• Support for various data types of resource attributes and id #1051
• Support for custom routes #1065
• Support for mixed projects #1066
• Support for ID obfuscation #1067
• Support for resource inheritance #1457
• OpenAPI: Support [DisableQueryString] #1461
• Explore usage of INotifyPropertyChanged with NSwag clients #1577

The state of the integration can be viewed in the openapi branch.

Feedback

The best way to give feedback is to create new issues or upvote/downvote existing ones.
Please give us feedback that will give us insight on the following points:

• Existing features that are missing some capability or otherwise don't work well enough.
• Missing features that should be added to the product.
• Design choices for a feature that is currently in-progress.

[wunki]

This is so exciting! This will catapult JADNC to the next level 🚀

[bkoelman]

For anyone that wants to try out the latest bits: pick a version with "openapi" in the name from https://github.com/json-api-dotnet/JsonApiDotNetCore#trying-out-the-latest-build.

[bkoelman]

JetBrains Rider has built-in IDE support for OpenAPI, see https://www.jetbrains.com/help/rider/OpenAPI.html.
Similar feature in Visual Studio Preview: https://devblogs.microsoft.com/visualstudio/web-api-development-in-visual-studio-2022/#endpoints-explorer

[bkoelman]

How to configure the NSwag C# client generator: https://github.com/RicoSuter/NSwag/wiki/NSwag-Configuration-Document and https://stevetalkscode.co.uk/openapireference-commands and https://github.com/RicoSuter/NSwag/blob/master/src/NSwag.CodeGeneration.CSharp/CSharpClientGeneratorSettings.cs.

[verdie-g]

@bkoelman what's the status of the OpenAPI integration? I could have a look if there is a isolated issue about it.

[bkoelman]

@verdie-g The OpenAPI integration is my primary priority. Picking up from @maurei's work, I've recently implemented support for triple-slash doc-comments, query string parameters, and included related resources in responses.

I've updated the list of work items and marked several with the good first issue label. Feel free to give it a try.

[maurei]

Happy to see this work is being picked up again! I wish I could devote a few months of my time to this again :-)

[bkoelman]

OpenAPI generation is being added in ASP.NET 9, replacing the Swashbuckle support in Visual Studio.

[verdie-g]

OpenAPI generation is being added in ASP.NET 9

Does it change the plans regarding this issue? If the current openapi branch is merged into master I suppose it will be hard to migrate to Microsoft.AspNetCore.OpenApi so maybe we should consider doing the migration now. Note that Microsoft.AspNetCore.OpenApi targets .NET 7+ and JADNC targets .NET 6+. Though, .NET 6 EOL is in November of this year so I suppose JADNC could drop .NET 6 then.

[bkoelman]

OpenAPI generation is being added in ASP.NET 9

Does it change the plans regarding this issue? If the current openapi branch is merged into master I suppose it will be hard to migrate to Microsoft.AspNetCore.OpenApi so maybe we should consider doing the migration now. Note that Microsoft.AspNetCore.OpenApi targets .NET 7+ and JADNC targets .NET 6+. Though, .NET 6 EOL is in November of this year so I suppose JADNC could drop .NET 6 then.

I've tried the built-in support in ASP.NET 9 preview4. It doesn't work at all with what we have today. The first issue is that the ApiExplorer integration (rewriting endpoints) is handled differently. The ASP.NET implementation is still in a very early stage and under active development. I've expressed our needs at dotnet/aspnetcore#54598 (comment), but the extension points we need don't yet exist. I don't think it makes sense to spend a lot of time on adopting it in the near future. And because Swashbuckle is now under active maintenance again, I suspect to finish our OpenAPI integration based on that. Because it is mature and stable, and our extensibility needs go way beyond what most other projects need.

[captainsafia]

@bkoelman Following up on the comment that you left in the issue on the ASP.NET Core repo here.

The Microsoft.AspNetCore.OpenApi implementation has evolved to cover some of the scenarios that you listed originally including:

• Creating custom reference ideas via OpenApiOptions.CreateSchemaReferenceId (in PR)
• Creating custom operation IDs for types (supported via EndpointName metadata)
• Reording paths in a document (supported via DocumentTransformers)
• Using different schemas to represent requests/responses by differing required/nullable states (supported by M.A.OpenAPI's schema-comparison based implementation for generating refs)

The biggest gap I noticed is around your schema generation-based customizations. Our implementation currently relies on the new JsonSchemaExporter APIs in System.Text.Json (.NET 9 Preview 6) and that layer doesn't have as many of the customizability options that Swashbuckle has. That being said, I'd be curious to understand the details of some of the items you mentioned in your bullet list from the comment above:

Custom handling of OpenAPI inheritance with allOf and discriminator that maps to JSON:API type

Do you use allOf to model inheritance hierarchies in your documents or is that something that you disable? This isn't an option that we currently support in M.A.OpenApi, primarily because its iffy whether or not allOf can be used to accuratnely model inheritance hierarchies in JSON schema.

What discriminators are you referring to in the statement above? At the moment, our implementation supports STJ's polymorphism attributes by default. Does your library provide a custom set?

For the JSON:API type, we generate a single-valued enum, so callers don't need to set a magic string

I assume you're doing this to work around the limitation in OpenAPI v3 that the JSON Schema const keyword is not supported? If so, I don't really have a good solution for that since our system has to comply with a similar constraint. We do expose a schema transformers concept (similar to schema filters) that can help here.

In JSON:API, sending null means to clear something, whereas not sending it means to leave it unchanged. So we need to handle OpenAPI required/nullable manually, ie [Required] on a property must not translate to non-nullable

Requiredness/nullability are modeled independently in our system so you should be able to model required properties that can be null if need be.

But to a more general point, I think your statement here:

And because Swashbuckle is now under active maintenance again, I suspect to finish our OpenAPI integration based on that. Because it is mature and stable, and our extensibility needs go way beyond what most other projects need.

is prudent and wise. It seems like you've done a lot of work in the area already building our Swashbuckle's model and I wouldn't through that away. In the future, it would be interesting to explore if you can extend this to support M.A.OpenAPI as well, and perhaps go even further and recommend some API changes to the underlying ApiExplorer metadata layer that both Swashbuckle/M.A.OpenAPI use for document generation to make your framework more resilient to whatever API document spec is supported.

I hope this information was helpful! If you have any inquiries about this work (particularly in regard to the more ASP.NET Core-related aspects), I'm happy to share insights.

[bkoelman]

Hi @captainsafia,

Thanks for the follow-up, I really appreciate the proactivity here.
I've created #1591 to respond and explore this further.