swagger 为通用控制器添加文档和操作

Question

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

但是当api开启api版本时，新版本swagger文档生成失败。它 returns 一个 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;
        }

Answer 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>();

希望对你有所帮助

swagger 为通用控制器添加文档和操作

swagger add document and operation for a generic controller

c#

swagger

.net-core

api-versioning