Have namespaces always been ignored when creating api docs? #1097
Replies: 2 comments · 7 replies
-
|
OpenAPI (formerly Swagger) never cared about namespaces because that is a .NET language concept which doesn't necessarily translate to other languages. If you have something like
The rules are as follows (in order):
OpenAPI and the Swagger UI do not support more than one level of grouping out-of-the-box. This is the closest you could ever get to it with the default tooling unless you change quite a number of things. If you group was This feature is documented in the wiki and was introduced in |
Beta Was this translation helpful? Give feedback.
-
|
Here is a link to our current docs based on .NET 6: docs This is still using the Microsoft.AspNetCore.Mvc.Versioning packages for versioning. After updating to .NET 8 and updating all the associated packages this no longer works. I get the exception about the dictionary key, the GroupName, already existing. I have been able to get it to work doing something similar to what you suggested by appending the apiVersion to the GroupName however we'd like to avoid that if at all possible. Something somewhere has changed but I have yet to figure it out. I also tried grouping by namespace but that was just confusing. |
Beta Was this translation helpful? Give feedback.
-
|
Every version of API Versioning has affinity to ASP.NET Core and its .NET TFM. In thinking more about the problem you are describing, there is something else happening. At least from API Versioning, there is no let dictionary = provider.Items
.GroupName(api => api.GroupName)
.ToDictionary(group => group.Key, group => group.ToArray());This still wouldn't produce a duplicate key on |
Beta Was this translation helpful? Give feedback.
-
|
here is the full exception:
|
Beta Was this translation helpful? Give feedback.
-
|
line 25 referenced in the exception is the |
Beta Was this translation helpful? Give feedback.
-
|
This image is from stepping through the code with a breakpoint on line 25 in NET 8 This is the same from NET 6 It's as if the definition of |
Beta Was this translation helpful? Give feedback.
-
|
Ok. I think I know what's going on here. I don't know how The I'm not sure what you are trying to achieve with I would encourage you to review the OpenAPI example project and, in particular, the ConfigureSwaggerOptions. |
Beta Was this translation helpful? Give feedback.
-
|
So originally the docs looked like this: Removing the We've lost the name grouping which is what we are trying to achieve. However, it sounds like we got what we wanted by happy chance rather than design. Thank you so much for your time and help. |
Beta Was this translation helpful? Give feedback.
-
|
Since you aren't using Swagger UI, it is still possible to transform the descriptions into another form. The default would by version and then API, but it seems you want to by group, version, and then API. This can be achieved with the [AttributeUsage(AttributeTargets.Class)]
public sealed class ApiGroupAttribute(string name) : Attribute
{
public string Name => name;
}Then you can apply it with: [ApiVersion(1.0)]
[ApiGroup("MDS")]
public class MdsController : ControllerBase
{
}Attributes are automatically collected by the Using all of that, you should be able to get the level of grouping you want. You just need to make sure that document name matches up. |
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
-
Hi. I put this here as I'm fairly sure it isn't a bug. We recently updated to .NET8 and also to AspNet-Api-Versioning. But now our docs don't build. I get an error telling me that a key, "Providers", has already been added to the dictionary. Tracking this down seems to lead me to the
[ApiExplorerSettings(GroupName = $"Providers_v2")]and the GroupName. To distinguish between versions I added_v2as a test and now my docs build correctly. In the previous version we didn't need to do this. But I came across this closed issue where it states namespaces are ignored; #1084So I was wondering if something had changed between versions?
Beta Was this translation helpful? Give feedback.
All reactions