大摇大摆地为通用控制器添加文档和操作答案

【问题标题】：swagger add document and operation for a generic controller大摇大摆地为通用控制器添加文档和操作
【发布时间】：2019-01-04 03:05:25
【问题描述】：

我正在开发一个带有插件的 webapi。我想在添加插件时更新 swagger 文档。当我不使用版本时，我可以处理这个问题。所有方法都添加到 swagger 文档中。

但是当api开启apiversion时，新版本swagger文档的生成失败。它返回 404。

我是否需要做任何事情才能使版本控制工作并获取动态控制器功能...

 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;
        }

【问题讨论】：

有几个可能的选项。在提供指导之前，您使用的是哪个 Swagger 生成器框架？ Swashbuckle、NSwag 等。根据标签，看起来这是针对 ASP.NET Core 的，是吗？
@ChrisMartinez 我正在使用 Swashbuckle.aspnetcore 4.01。目前，我有一个解决方法，方法是指向自己的 json 文档控制器并自己在那里生成文档。（使用招摇发生器）。但这感觉就像一个黑客......see the example here

标签： c# .net-core swagger api-versioning

【解决方案1】：

我现在明白了。您正在使用自己的版本控制机制并按需生成 Swagger 文档。 Swashbuckle 希望一切都预先定义。这是合理的，因为支持的版本应该在应用程序启动时是确定的。如果您的应用程序是完全动态的，那么您当前的解决方案将有效，但在调用之间可能会有所不同。如果插件被提前发现并加载，那么您可以注册一个IConfigureOptions<SwaggerGenOptions>，使用您的插件信息配置 Swashbuckle。比如：

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
    }
}

然后在服务容器中注册：

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

希望对你有帮助

【讨论】：