swagger add document and operation for a generic controller

Question

i am working on a webapi with plugins. I want to update the swagger documentation when a plugin is added. I can handle this when i don't use version. All methods are added to the swagger documentation.

but when the api has apiversion turned on, the generation of the new version swagger document failed. It returns a 404.

do i need to so anything for versioning to work and pick up the dynamic controller functions...

 private string AddSwaggerVersionDocument(PluginMetadata metadata)
        {

            var version = metadata.Version.ToApiVersion();

            if (SwaggerElements.GeneratorOptions.SwaggerGeneratorOptions.SwaggerDocs.ContainsKey(version) == false)
            {
                SwaggerElements.GeneratorOptions.SwaggerDoc(version, new Info
                {

                    Title = "webapi API",
                    Version = $"{version}",
                    Description = "Web API demo",
                    TermsOfService = "None",
                    Contact = new Contact
                    {
                        Name = "Frans van Ek",
                        Email = string.Empty,
                        Url = "https://fransvanek.nl"
                    },
                    License = new License
                    {
                        Name = "Use under LICX",
                        Url = "https://fransvanek.nl"
                    }
                });

                 SwaggerElements.UIOptions.SwaggerEndpoint($"/swagger/{version}/swagger.json", $"My API : {version}");
            }
            return version;
        }

There are couple of possible options. Before providing guidance, which Swagger generator framework are you using? Swashbuckle, NSwag, etc. Based on the tags, it looks like this is for ASP.NET Core, yes? — Chris Martinez, Dec 23 '18 at 01:58
@ChrisMartinez I am using Swashbuckle.aspnetcore 4.01. Currently I have a workaround by pointing to a own controller for the json doc and generating the documentation there myself. (using the swagger generator). But it feels like a hack... [see the example here](https://stackoverflow.com/questions/53869774/call-swagger-generator-for-plugins) — Frans, Dec 24 '18 at 06:40

score 0 · Accepted Answer · answered Jan 03 '19 at 19:05

I see now. You're using your own versioning mechanism and generating Swagger documents on-demand. Swashbuckle expects everything to be defined upfront. This is reasonable as the supported versions should be deterministic at the start of the application. If your application is completely dynamic, then your current solution will work, but can vary between invocations. If plug-ins are discovered and loaded ahead of time, then you can register an IConfigureOptions<SwaggerGenOptions> that configures Swashbuckle with your plugin information. Something like:

public class ConfigureSwaggerOptions : IConfigureOptions<SwaggerGenOptions>
{
    readonly IApiDescriptionGroupCollectionProvider provider;

    public ConfigureSwaggerOptions(
        IApiDescriptionGroupCollectionProvider  provider ) => this.provider = provider;

    public void Configure( SwaggerGenOptions options )
    {
        // TODO: configure swashbuckler with plug-in information
    }
}

And then register it in the service container with:

services.AddTransient<IConfigureOptions<SwaggerGenOptions>, ConfigureSwaggerOptions>();

I hope that helps

swagger add document and operation for a generic controller

1 Answers1

Linked