How to support multiple swagger files per version/group?

[mattmazzola]

This is a question about best practices to achieve the multi swagger generation per version rather than specific issue with library. Hope someone can help or suggest a work around.

Background:

We have existing Asp.net core service that was using hard coded url versioning such as [Route("api/v1/app")]. We also have certain controller actions separated into groups to generate two different swagger files for Azure APIM. These different operations needed to be billed and managed differently (throttling, quota, etc). We did this by using the group name:

[ApiExplorerSettings(GroupName = "authoring")]
Controller1

[ApiExplorerSettings(GroupName = "session")]
Controller2

and then manually generating matching swagger files

c.SwaggerEndpoint("/swagger/authoring/swagger.json", ... )
c.SwaggerEndpoint("/swagger/session/swagger.json", ... )

Intention

We wanted to add a new version (2.0) to the app to change the urls to more closely align with the Microsoft REST guidelines and wanted to set it up in a scalable way based on the sample https://github.com/microsoft/aspnet-api-versioning/tree/master/samples/aspnetcore/SwaggerSample
this is involved changes to AddApiVersioning, AddVersionedApiExplorer, and most notably how the swagger files are generated.

We wanted to preserve the separate of authoring and session operates and hoped to be able to generate two files per version descriptor such as:

foreach (var description in provider.ApiVersionDescriptions)
{
    c.SwaggerEndpoint($"/swagger/authoring-{description.GroupName}/swagger.json", description.GroupName.ToUpperInvariant());
    c.SwaggerEndpoint($"/swagger/session-{description.GroupName}/swagger.json", description.GroupName.ToUpperInvariant());
}

to achieve something like this:

/v1
  /authoring/swagger.json
  /sesssion/swagger.json
/v2
  /authoring/swagger.json
  /session/swagger.json

However there seems to be catch-22 situation. It seems Swagger/Swashbuckle was using group name to associate operations and generate files. If we change group name to be generic ''v'VVV" it means we can no longer use the split the actions/operations between the groups using the [ApiExplorerSettings(GroupName = "session")] attribute since it is one group per version. If we keep the specific groups then we can't generate them dynamically from the version descriptors because the group names ("authoring" and "session" won't map to the versions "v1" and "v2" etc.

Our thought was maybe there is some hack like making the version name include a slash such as
v{version}/authoring and v{version}/session but that would increase complexity and put us off standard sample for people to help us.

Our only current idea is to go to generic versioning with single swagger per version and sepearate the authoring vs session groups by moving it to a new .net core project. That is a much larger work than we thought as we have to re-architect to share resources across them and thus creating this issue asking for help.

[commonsensesoftware]

Most Swagger generations, at least all the ones I've seen, provide a single hierarchy in the user interface. In ASP.NET Core, this is typically driven by the GroupName. The API Versioning extensions always group by API version, which is typically what service authors want.

In your particular case, you have two hierarchical levels. This cannot be achieved directly though the GroupName alone; you need two properties/discriminators. To get your desired result, you've to customize things on the Swashbuckle side; specifically, the user interface. It should be simple enough to group and build endpoint URLs by API version and billing name, but you'll need two dropdown lists to drive it.

To minimize the work, I would consider moving your billing group name to a custom attribute that you can retrieve by away of an extension method. Something like:

[ApiVersion("1.0")]
[BillingGroup("authoring")]
public class Controller1 : ControllerBase
{
}

Of course, you don't really need to have split the Swagger documents up this way unless you're trying to reduce the size of the documents or focus in on relevance. If you just want to filter by relevance, it might be easier to just tweak the client-side scripts to support filtering API sets. They'll already be grouped by API version.

It's possible for you to flat the list down to API Version + Billing Group in the GroupName, but you'll need a custom IActionDescriptionProvider to do it. I would still recommend using a custom attribute, but then it should be easy to combine the two parts into a single value the way you want.

It should be possible to use a custom Swagger document generator or operation filter in Swashbuckle to achieve a similar result.

I hope that gives you a few ideas.

[mattmazzola]

Thanks for replying. It does give us some ideas although we're not quite sure how to take action on them. It sounds like we would need to customize the generation of Swagger files through modifying Swashbuckle and I'm not familiar with that process.

I will try to rewrite what you suggested to make sure I understand and ask questions about parts. There were two main parts I was confused about.

you don't really need to have split the Swagger documents up this way unless you're trying to reduce the size of the documents or focus in on relevance.

I will have to look into this more. It was my understanding we associated a single unfiltered swagger doc per APIM endpoint. (E.g. authoring endpoint was 1 swagger.json and session endpoint was another swagger.json) This was the driving factor for needing separate documents. (We have 2 per version) And with addition of new version we would have 4.

Are you saying it's possible for us to only generate 1 document per version (instead of sub split by author and session) and then somehow filter on APIM so it only sees a subset of the operations?

On the suggestion of customizing swashbuckle:

To get your desired result, you've to customize things on the Swashbuckle side; specifically, the user interface. It should be simple enough to group and build endpoint URLs by API version and billing name, but you'll need two dropdown lists to drive it.

That was the intention to end up with 4 swagger files. (v1 / authoring, v1 / session, v2 / authoring, v2 / session, etc) If the above question about filtering is possible then maybe this isn't needed.

If we do need to generate individual files then yes, I think we would need 2 dropdowns (1 per hierarchy). There would be a top level dropdown for version which exists now. Which would map to the ApiVersion / GroupName as those would be in alignment.

The second drop down would be for the billing group of authoring and session.

How would we go about modifying Swashbuckle to have these 2 dropdowns using our second custom attribute?
Is there an extension method we can over ride? This is more likely for us to try.
Or do we have to modify their source something more challenging? We wouldn't want to be on a special fork of library.

[commonsensesoftware]

To clarify, when you use the API Explorer extensions provided by API versioning, you would end up with a Swagger document per API version that contains all applicable APIs. For example:

• swagger/v1/swagger.json
  • api/sessions
  • api/authoring
• swagger/v2/swagger.json
  • api/sessions
  • api/authoring

I've had people ask me about having a Swagger document per resource (e.g. group) and then list all the different versions in the document. APIs that follow the REST constraints aren't able to fit into this model because Swagger does not allow duplicate URLs. Since you're versioning by URL segment (the least RESTful method), it's technically possible for this work, but it don't think it would go far in helping clients review and test out APIs since you'd see the same name multiple times or names like Sessions 1.0 and Sessions 2.0 (unless you don't mind that).

I don't profess to be an expert in Swagger (the doc or UI) nor any of the numerous frameworks that exist out there. I have some familiarity with Swashbuckle and its author. The type of advanced customization you seem to be describing isn't unheard of. If you were just trying to put up simple documentation endpoint for your internal services, I could see the resistance to investing in extensive customization. It seems you're trying to document a monetizable product, which may warrant the investment. The Swagger UI is meant to serve the 80%, but it sounds like you might be in the 20%. It's completely up to you whether you want to live within its intrinsic, out-of-the-box limitations or extend it, which may involve forking the UI. You might want to review the Swagger UI documentation for more information. Some folks within Microsoft built their own UI so that's always an option for you too.

[mattmazzola]

I've had people ask me about having a Swagger document per resource (e.g. group) and then list all the different versions in the document.

In other words, having a hierarchy of group -> version as opposed to version -> group. We considered this but agree Version as top level is better for us. It's similar to your list above with the second level of hierarchy.

Version -> Group

/v1 (Version)
  /authoring (Group)  (swagger/v1/authoring/swagger.json)
    /endpointA (Controller Action)
    ...
  /session (swagger/v1/session/swagger.json)
   /endpointB
   ...

/v2
  /authoring (swagger/v2/authoring/swagger.json)
    /endpointA
    ...
  /session (swagger/v2/session/swagger.json)
    /endpointB
    ...

you'd see the same name multiple times or names like Sessions 1.0 and Sessions 2.0

I didn't understand what scenario or conditions would make this occur. I assumed thee would be v1 and v2 swagger docs and both have an session group / endpoint operation. I thought this was expected.

which may involve forking the UI

Yes, we will probably avoid that as maintaining the changes as the origin updates is a too much for our small team. Also, I think we're more concern about the generation of the files and not simply being able view them in the UI. Based on previous discussion in thread the services.AddSwaggerGen only generates 1 per group / version and would not understand to generate based on the separate custom header you proposed as BillingGroup. Since we would also need to fork this then it's definitely too much.

[commonsensesoftware]

"I didn't understand what scenario or conditions would make this occur"

This would happen in the group->version scenario because you'd have the same routes per group, but grouped by version.

Since changing the out-of-the-box experience is not an option for you, I really can only think of two recommendations.

Option 1

Use it as is to produce the version->group layout. There will be a single Swagger document per API version. You didn't say why this wouldn't work for you, but all things considered, it's the simplest and lowest effort to implement.

Option 2

Create and register a custom IActionDescriptionProvider that runs after API Versioning. In the OnExecuted method, you'll be at the end with everything collated by API version. At this point, you should reorder everything and bucketize based on API Version + Billing Group. This is place where your custom [BillingGroup] attribute can come into play. You can extract the value from this attribute and concatenate it with the API version. If your provider injects IOptions<ApiExplorerOptions>, then you'll have access to the configured formatting options - if you care; otherwise, you can format things inline. The ApiVersion implements IFormattable. The formatting codes and options are in the wiki.

The really tricky part is trying to filter the billing group. The IActionDescriptionProvider design doesn't really support this concept. I'm struggling to think of how you can make this work on the ASP.NET Core side. This is the kind of thing where a feature could be used based on the incoming request, but this API doesn't have a way to access the incoming request. That makes it very difficult to filter things. I think you'd have to do this filtering on the Swashbuckle side with a custom Swagger generator or something. I don't have an example of exactly how and where you do it, but it should be possible for the entire document or specific operations. You should be able to extend and replace the default implementation without a lot of effort. The only thing you're really doing is filtering things down.

With all of this in place, you'll end up with single Swagger dropdown that looks something like:

• Authoring 1.0
• Authoring 2.0
• Sessions 1.0
• Sessions 2.0

---

I don't know if that's what you really want, but those are the only two ways I can think of you can make this work without doing some significant customization.

[commonsensesoftware]

Did this help or otherwise answer your question?

[commonsensesoftware]

It appears that the suggestions provided helped you find a solution or you used another approach. If you weren't able to solve your issue, feel free to come back or reopen the issue. Thanks.

[mattmazzola]

Sorry, I should have responding earlier. There were some changes with product that came above versioning which delayed investigation and also I kept waiting to find out more concrete answers from my co-worker about APIM and swagger, but I never did and thus didn't reply. I will just reply with what I know now.

We haven't solved the issued, but it's mostly because of inaction. We feel a bit stuck. It seems option 1 didn't solve the issue (at least how we interpreted it, details below) and option 2 was likely too much custom work which we're resistant to invest in since we don't know it will work. However, you can keep the issue closed for now until we get more clarity on swagger requirements and we're at a point to put more effort in.

Option 1

There seems to be confusion about the default implementation and what we want. We want the version -> group hierarchy (meaning each version has authoring and session groups within it as shown in sample URLs in my post above), however, in the default implementation there is no hierarchy.
In your explanation you associate Option 1 with "Use it as is" (default implementation), but using as is means the version is the group.
Out original intention was to use as is, but this results in authoring and session API's for the same version in the same swagger file.

swagger/v1/swagger.json

/v1/authoring/endpoint
/v1/session/endpoint

You didn't say why this wouldn't work for you

I meant to say it in the above post.

I will have to look into this more. It was my understanding we associated a single unfiltered swagger doc per APIM endpoint. (E.g. authoring endpoint was 1 swagger.json and session endpoint was another swagger.json) This was the driving factor for needing separate documents. (We have 2 per version) And with addition of new version we would have 4.

This was one of the pieces of information I was waiting on. If we can give APIM a swagger file and a filter on which operations from that file, this would work and remove need for separate files. I still need to confirm that this IS or IS NOT possible.

Option 2

This does produce what we want, but due to extra complexity we're not sure. If there was some sample we could compare and reference as we try that could work, but we haven't tried this. We were also worried about going non-standard and being compatible with other teams services so they could overlap the maintenance.

Hope that at least clears up the situation.

[commonsensesoftware]

No problem. Since I'm running this project alone, I keep the issues list well-pruned. After question-based issues go dark, I usually ping with a follow up and give people a week or so. After that I assume they either fixed their issue, found another solution, or abandoned things altogether.

If you only need a particular layout for APIM, then you might consider using the Swagger/OpenAPI library of choice and generating the *.json files yourself. The URL conventions are purely about serving the files directly from your own application. If your uploading the document to APIM, then you shouldn't have to worry about that. You can generate the documents however you like. A single document can contain one or more sets of APIs per version (which is the default behavior). There's nothing wrong with creating a single document per API, per version, but I believe you'd have to generate that yourself. A single document cannot contain multiple versions of an API unless you version by URL segment, which I never recommend.

By generating the documents yourself, you might have tool that outputs:

• authoring.v1.json
• authoring.v2.json
• session.v1.json
• session..v2.json
• …

Each document contains a single API per version. I'm not super familiar with the details of APIM, but I presume each of these documents should be suitable for upload.

You could also customize a tool like Swashbuckle to serve up the same documents. The mapping ends up looking something Authoring 1.0 -> ~/authoring.v1.json. Grouping by name is not a requirement of a Swagger/OpenAPI document. The support provided in the API Explorer affords creating a group per logical name for an API. Unfortunately, it doesn't include multiple levels of grouping. When you introduce versioning, most cases need to be grouped by API version or the document would become invalid because you cannot have duplicate URLs. As I mentioned before, the only other way I can think of that would address that is combining the API name with the API version into a single level of grouping.

I hope that helps. Happy to continue providing whatever guidance you may need.

[tjmcnaboe]

I had a similar intent. This will not get you exactly what you want but might be close enough for your needs with a very minimal amount of effort.
In Startup.cs change options group format to this if it is not already. : options.GroupNameFormat = "'v'VVV";
The Api Version attribute forces you to use a int for the 1st and 2nd values however for the 3rd you can use alphanumeric so then you can do this:
[ApiVersion( "3.0.session" )]
[ApiVersion( "3.0.authoring" )]
[Route("api/v{version:apiVersion}/[controller]")]

which will produce a swagger document for each api per version and routes like this:
/api/v3-authoring/Orders/5
/api/v3-session/Orders/{id}

which is very close to what you prob want which is this api/session-v3

Hope that helps