azure-functions-openapi-extension

azure-functions-openapi-extension copied to clipboard

This fixes #153 by using reference types for Enum properties. Enums in query/path url parameters are NOT updated to use reference types. In OAS v2, enum query/url params must be inline. v3 supports using $ref. To implement this, we need to have the target version in StringEnumTypeVisitor.PayloadVisit / ParameterVisit to determine whether to return a $ref or inline enums, which would require some structural changes. Maybe there's a better way to do that, perhaps after the visitors while rendering the doc, but I would need some more guidance.

Breaking changes:

If the project contains multiple Enum type definitions with the same name (for example, https://github.com/Azure/azure-functions-openapi-extension/issues/153#issuecomment-932121161 ), these will now conflict. One possible workaround would be to provide a type name callback/delegate, eg Func<Type, string> GetTypeName, where consumers of this lib who have this conflict could provide an alternative type name, eg by including the parent namespace.

All CLA requirements met.

Thanks, @rockgecko-development for the long wait! Because it's too big to ingest, I need to take some times to take a look. I'll get back to you once I complete review.

Also, as you mentioned, it might require breaking changes. Let's keep the conversation open and going.

Thanks, let me know what you need to get this across the line. There also will be breaking changes on the consumer side, if using a codegen tool. Currently, most codegen would give enum property types a name derived from the containing model name. This will now change to the original C# name (which is the whole intent of this PR). (url/query enums will remain inline for now, and codegen would continue to derive the name from the endpoint and parameter name).

In #153, @level120 mentioned that we need to figure out #248 first. If we follow that path, does this impact on your PR as well?

#248 is referring to fields with the same name as the type. That doesn't seem specifically relevant to enums. #153 is about the conflict if users have nested enums with simple, reused names like Status defined inside multiple classes. That would cause the kind of conflict I mentioned in my OP. I haven't seen any suggested solutions other than the one I proposed above: provide a type name callback/delegate, eg Func<Type, string> GetTypeName in OpenApiConfigurationOptions, where consumers of this lib who have this conflict could provide an alternative type name, eg by including the parent namespace.

To implement this I would need some guidance from you in how to access this new config from within StringEnumTypeVisitor, as the visitors currently do not seem to have any context or configuration.

#610 has taken care of this issue.