Swagger 文档：Swashbuckle（隐藏方法/属性）答案

【问题标题】：Swagger documentation: Swashbuckle (hide methods/properties)Swagger 文档：Swashbuckle（隐藏方法/属性）
【发布时间】：2016-11-16 13:13:38
【问题描述】：

我正在使用 Swagger Swashbuckle 生成文档。我的控制器中有一些方法和模型中有一些我不想记录的属性。是否有任何 arrtibute 或属性可以离开或忽略文档中的特定方法？

【问题讨论】：

标签： swagger swashbuckle

【解决方案1】：

对于该方法，您有几个选择：

使用过时属性。然后，您必须在 swagger 配置中设置操作 - c.IgnoreObsoleteActions();
创建自定义属性和 swagger 文档过滤器。如果方法具有自定义属性，则文档过滤器应遍历每个方法并删除方法文档

对于属性，您可以使用JsonIgnoreAttribute

【讨论】：

第二种方法有什么例子吗？

【解决方案2】：

除了c.IgnoreObsoleteActions()，还有c.IgnoreObsoleteProperties()，它在文档中隐藏了属性。

JsonIgnoreAttribute 将在作为 POST 请求正文的一部分接收时停止属性反序列化，如果您只想更改文档而不是功能，这可能不是您想要的。

【讨论】：

我将装饰器 [Obsolete] 用于我想要隐藏的属性，并在启动时放置 c.IgnoreObsoleteProperties()。虽然该属性隐藏在大摇大摆中，但它在响应中仍然可见。我使用 asp.net 核心。如何在招摇中隐藏对用户完全可见的属性？
如果您也想隐藏响应，我认为您希望 JsonIgnoreAttribute 像傻约翰的回答一样在属性上

【解决方案3】：

在最新版本的 Swashbuckle (Core2/3) XmlIgnore/JsonIgnore 中似乎不适用于属性。
或者，您可以将属性访问修饰符更改为 internal。这应该可以防止序列化和生成文档。

我不确定是否要隐藏整个控制器，您可能需要在 Swagger 设置中添加过滤器。我确实有一个隐藏某些端点的示例（为方便起见，我为本地运行的路由添加了前缀）：

        public void ConfigureServices(IServiceCollection services)
        {
            ...
            services.AddSwaggerGen(config => {
                config.SwaggerDoc("v1",
                    new OpenApiInfo {
                        Version = "v1",
                        Title = "Foo API",
                        Description = "Does foo things.",
                        Contact = new OpenApiContact {
                            Name = "nope",
                            Email = "mail@example.org",
                        },
                    });
                // Include XML comments in Swagger docs
                var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
                config.IncludeXmlComments(xmlPath);
                // Filter out prefixed routes
                config.DocInclusionPredicate(
                    (name, desc) => !desc.RelativePath.ToLower().StartsWith("MyDevPrefix"));
            });
    }

【讨论】：

【解决方案4】：

请注意，因为我还试图找出 JsonIgnore 的属性不起作用...

问题似乎在于 .Net Core 的新版本 Swashbuckle 不支持开箱即用的 NewtonSoft。

从 NuGet 安装

Package Manager : Install-Package Swashbuckle.AspNetCore.Newtonsoft -Version 5.6.2
CLI : dotnet add package --version 5.6.2 Swashbuckle.AspNetCore.Newtonsoft

将代码添加到 startup.cs

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
});
services.AddSwaggerGenNewtonsoftSupport(); // explicit opt-in - needs to be placed after AddSwaggerGen()

这对我有用，希望这对其他人有帮助。

【讨论】：

【解决方案5】：

这里有一个更新的答案：

正如其他人提到的 - 忽略属性（文档和真实响应）使用属性：[JsonIgnore]
要从文档中隐藏控制器/操作（控制器/操作仍然存在，它只是从文档中隐藏）使用属性：[ApiExplorerSettings(IgnoreApi = true)]

【讨论】：