Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Support in-memory only metadata dictionary in OpenAPI object model #1719

Open
captainsafia opened this issue Jul 8, 2024 · 4 comments
Open

Comments

@captainsafia
Copy link
Member

Is your feature request related to a problem? Please describe.
Currently, all properties within the OpenAPI object model are serialized to the output as part of the OpenAPI writer implementation. This makes it difficult to manage temporary state associated with the in-memory OpenAPI model. For example, ASP.NET Core needs to correlate a given OpenApiOperation with a unique identifier for each endpoint recognized by the framework.

Describe the solution you'd like
The OpenAPI object model should support some sort of property bag that allows users to manage metadata associated with an object model in-memory without having to worry about information in this property bag being serialized.

public class OpenApiHasPropertyBag
{
	IDictionary<string, object> MetadataCollection { get; }
}

Describe alternatives you've considered
Currently, ASP.NET Core works around this limitation by storing the metadata in the Extensions property on OpenApiSchema and OpenApiOperation then scrubbing this metadata out from the in-memory model before it is serialized. This presents a couple of issues:

  • The additional cost of having to scrub out metadata that doesn't need to be serialized
  • The additional cost of mapping property bag values to OpenApiAny implementers
@captainsafia
Copy link
Member Author

@baywet @MaggieKimani1 @darrelmiller Any thoughts on the API shape proposed here? I know the library makes extensive use of interfaces for things like this but it strikes me that using a base class would reduce the implementation overhead.

With regard to what classes will extend OpenApiHasPropertyBag, I'm thinking that we should start with:

  • OpenApiDocument
  • OpenApIPath
  • OpenApiOperation
  • OpenApiSchema

@baywet
Copy link
Member

baywet commented Jul 10, 2024

From what I remember from this code base, having a base class would go against the general design.
The extensive use of interfaces for every facet has been the design here.
I wonder if interface default implementations could help us get the best of both here?

From a scenario perspective I'm not sure I understand what you'd expect OAS.net to do with that property bag besides storing it in memory?

@captainsafia
Copy link
Member Author

I wonder if interface default implementations could help us get the best of both here?

Good idea! An interface with a default property implementation can help fill the gap here. My other conondrum was more bike-sheddy. A lot of the interfaces already defined have end in some sort of ble suffix (Extensible, Serializable, Referenceable). I couldn't think of a good one for this but I'm open to ideas.

From a scenario perspective I'm not sure I understand what you'd expect OAS.net to do with that property bag besides storing it in memory?

Yep, just store it in-memory. It's only there to provide a space for consumers of the object model to do book-keeping on instances within the object model. To elaborate on the ASP.NET Core scenario I described above, we'd use the property pag to store a unique identifier on a given OpenApiOperation instance that acts as a join ID with the ActionDescriptor concept in ASP.NET Core so we can link the OpenApiOperation instance with the framework type associated with it.

@baywet
Copy link
Member

baywet commented Jul 11, 2024

Thanks for the additional context!

For the name : IPropertyBagStorable? ugly, but explicit

What would you expect to happen with copy constructors? reference copy or deep copy?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants