我有一个c# ASP。使用Swashbuckle自动生成带有API文档的NET WebAPI应用程序。我想能够从文档中省略某些方法，但我似乎不知道如何告诉Swagger不包括他们在Swagger UI输出。
我觉得这与添加模型或模式过滤器有关，但不清楚要做什么，文档似乎只提供了如何修改方法输出的示例，而不是完全从输出中删除它。
在swagger文档使用文档过滤器生成后，您可以从该文档中删除“operations”—只需将谓词设置为null(不过，也可能有其他方法可以做到这一点)
下面的示例只允许GET动词—并且是从这个问题中选取的。
class RemoveVerbsFilter : IDocumentFilter
{
public void Apply(SwaggerDocument swaggerDoc, SchemaRegistry schemaRegistry, IApiExplorer apiExplorer)
{
foreach (PathItem path in swaggerDoc.paths.Values)
{
path.delete = null;
//path.get = null; // leaving GET in
path.head = null;
path.options = null;
path.patch = null;
path.post = null;
path.put = null;
}
}
}
在你狂妄自大的装扮中:
...EnableSwagger(conf =>
{
// ...
conf.DocumentFilter<RemoveVerbsFilter>();
});
我更倾向于完全删除路径项的字典条目:
var pathsToRemove = swaggerDoc.Paths
.Where(pathItem => !pathItem.Key.Contains("api/"))
.ToList();
foreach (var item in pathsToRemove)
{
swaggerDoc.Paths.Remove(item.Key);
}
使用这种方法，您将不会在生成的swagger中获得“空”项目。json定义。
有人在github上发布了解决方案，所以我要把它粘贴到这里。所有功劳都归他。https://github.com/domaindrivendev/Swashbuckle/issues/153#issuecomment-213342771
首先创建一个Attribute类
[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class)]
public class HideInDocsAttribute : Attribute
{
}
然后创建一个Document Filter类
public class HideInDocsFilter : IDocumentFilter
{
public void Apply(SwaggerDocument swaggerDoc, SchemaRegistry schemaRegistry, IApiExplorer apiExplorer)
{
foreach (var apiDescription in apiExplorer.ApiDescriptions)
{
if (!apiDescription.ActionDescriptor.ControllerDescriptor.GetCustomAttributes<HideInDocsAttribute>().Any() && !apiDescription.ActionDescriptor.GetCustomAttributes<HideInDocsAttribute>().Any()) continue;
var route = "/" + apiDescription.Route.RouteTemplate.TrimEnd('/');
swaggerDoc.paths.Remove(route);
}
}
}
然后在Swagger配置类中，添加该文档过滤器
public class SwaggerConfig
{
public static void Register(HttpConfiguration config)
{
var thisAssembly = typeof(SwaggerConfig).Assembly;
config
.EnableSwagger(c =>
{
...
c.DocumentFilter<HideInDocsFilter>();
...
})
.EnableSwaggerUi(c =>
{
...
});
}
}
最后一步是在你不希望Swashbuckle生成文档的控制器或方法上添加[HideInDocsAttribute]属性。
基于@spottedmahns的回答。 我的任务是反过来。只显示那些被允许的。
框架:.NetCore 2.1;轻便:3.0.0
添加属性
[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class)]
public class ShowInSwaggerAttribute : Attribute
{
}
并实现自定义IDocumentFilter
public class ShowInSwaggerFilter : IDocumentFilter
{
public void Apply(SwaggerDocument swaggerDoc, DocumentFilterContext context)
{
foreach (var contextApiDescription in context.ApiDescriptions)
{
var actionDescriptor = (ControllerActionDescriptor) contextApiDescription.ActionDescriptor;
if (actionDescriptor.ControllerTypeInfo.GetCustomAttributes<ShowInSwaggerAttribute>().Any() ||
actionDescriptor.MethodInfo.GetCustomAttributes<ShowInSwaggerAttribute>().Any())
{
continue;
}
else
{
var key = "/" + contextApiDescription.RelativePath.TrimEnd('/');
var pathItem = swaggerDoc.Paths[key];
if(pathItem == null)
continue;
switch (contextApiDescription.HttpMethod.ToUpper())
{
case "GET":
pathItem.Get = null;
break;
case "POST":
pathItem.Post = null;
break;
case "PUT":
pathItem.Put = null;
break;
case "DELETE":
pathItem.Delete = null;
break;
}
if (pathItem.Get == null // ignore other methods
&& pathItem.Post == null
&& pathItem.Put == null
&& pathItem.Delete == null)
swaggerDoc.Paths.Remove(key);
}
}
}
}
ConfigureServices代码:
public void ConfigureServices(IServiceCollection services)
{
// other code
services.AddSwaggerGen(c =>
{
// other configurations
c.DocumentFilter<ShowInSwaggerFilter>();
});
}
制作一个滤镜
public class SwaggerTagFilter : IDocumentFilter
{
public void Apply(SwaggerDocument swaggerDoc, DocumentFilterContext context)
{
foreach(var contextApiDescription in context.ApiDescriptions)
{
var actionDescriptor = (ControllerActionDescriptor)contextApiDescription.ActionDescriptor;
if(!actionDescriptor.ControllerTypeInfo.GetCustomAttributes<SwaggerTagAttribute>().Any() &&
!actionDescriptor.MethodInfo.GetCustomAttributes<SwaggerTagAttribute>().Any())
{
var key = "/" + contextApiDescription.RelativePath.TrimEnd('/');
swaggerDoc.Paths.Remove(key);
}
}
}
}
创建一个属性
[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class)]
public class SwaggerTagAttribute : Attribute
{
}
在startup.cs中申请
services.AddSwaggerGen(c => {
c.SwaggerDoc(1, new Info { Title = "API_NAME", Version = "API_VERSION" });
c.DocumentFilter<SwaggerTagFilter>(); // [SwaggerTag]
});
为你想包含在Swagger JSON中的方法和控制器添加[SwaggerTag]属性
在SwaggerConfig中添加一行
c.DocumentFilter<HideInDocsFilter>();
...
public class HideInDocsFilter : IDocumentFilter
{
public void Apply(SwaggerDocument swaggerDoc, SchemaRegistry schemaRegistry, IApiExplorer apiExplorer)
{
var pathsToRemove = swaggerDoc.Paths
.Where(pathItem => !pathItem.Key.Contains("api/"))
.ToList();
foreach (var item in pathsToRemove)
{
swaggerDoc.Paths.Remove(item.Key);
}
}
}
可能会帮助某些人，但在开发(调试)期间，我们喜欢暴露整个控制器和/或动作，然后在生产(发布构建)期间隐藏它们
#if DEBUG
[ApiExplorerSettings(IgnoreApi = false)]
#else
[ApiExplorerSettings(IgnoreApi = true)]
#endif
像@aleha一样，我想在默认情况下排除，这样我就不会意外地暴露端点(默认情况下是安全的)，但使用的是使用OpenApiDocument的Swagger的新版本。
创建一个ShowInSwagger属性
[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class)]
public class ShowInSwaggerAttribute : Attribute
{}
然后创建一个文档过滤器
using Microsoft.AspNetCore.Mvc.Controllers;
using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
using System.Reflection;
using System;
using System.Linq;
using TLS.Common.Attributes;
namespace TLS.Common.Filters
{
public class ShowInSwaggerFilter : IDocumentFilter
{
public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
{
foreach (var contextApiDescription in context.ApiDescriptions)
{
var actionDescriptor = (ControllerActionDescriptor)contextApiDescription.ActionDescriptor;
if (actionDescriptor.ControllerTypeInfo.GetCustomAttributes<ShowInSwaggerAttribute>().Any() ||
actionDescriptor.MethodInfo.GetCustomAttributes<ShowInSwaggerAttribute>().Any())
{
continue;
}
else
{
var key = "/" + contextApiDescription.RelativePath.TrimEnd('/');
var operation = (OperationType)Enum.Parse(typeof(OperationType), contextApiDescription.HttpMethod, true);
swaggerDoc.Paths[key].Operations.Remove(operation);
// drop the entire route of there are no operations left
if (!swaggerDoc.Paths[key].Operations.Any())
{
swaggerDoc.Paths.Remove(key);
}
}
}
}
}
}
然后在startup.cs或ConfigureServices中:
public void ConfigureServices(IServiceCollection services)
{
// other code
services.AddSwaggerGen(c =>
{
c.DocumentFilter<ShowInSwaggerFilter>();
// other config
});
}
您可以在控制器和方法级别上创建自定义过滤器。所以任何带有你属性的控制器/方法都可以在Swagger文档中找到。该过滤器还从文档中删除了重复的HTTP谓词(在本例中，它仅用于GET/PUT/POST/PATCH)，但是，您始终可以根据自己的需求进行自定义
属性
[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class)]
public class PublicApi:Attribute
{
}
文件过滤器
public class PublicApiFilter : IDocumentFilter
{
public void Apply(SwaggerDocument swaggerDoc, SchemaRegistry schemaRegistry, IApiExplorer apiExplorer)
{
var publicPaths = new List<string> {"/api"};
var publicApiDescriptions = new List<ApiDescription>();
var publicMethods = FilterByPublicControllers(swaggerDoc, apiExplorer, publicPaths, publicApiDescriptions);
FilterByPublicActions(swaggerDoc, publicApiDescriptions, publicMethods);
}
private static Dictionary<string, List<string>> FilterByPublicControllers(SwaggerDocument swaggerDoc, IApiExplorer apiExplorer, List<string> publicPaths, List<ApiDescription> publicApiDescriptions)
{
var publicMethods = new Dictionary<string, List<string>>();
foreach (var apiDescription in apiExplorer.ApiDescriptions)
{
var isPublicApiController = apiDescription.ActionDescriptor.ControllerDescriptor.GetCustomAttributes<PublicApi>().Any();
var isPublicApiMethod = apiDescription.ActionDescriptor.GetCustomAttributes<PublicApi>().Any();
if (!isPublicApiController && !isPublicApiMethod)
{
continue;
}
var relativePath = ToRelativePath(apiDescription);
publicPaths.Add(relativePath);
publicApiDescriptions.Add(apiDescription);
var action = apiDescription.ActionDescriptor.ActionName;
List<string> available = null;
if (!publicMethods.TryGetValue(relativePath, out available))
publicMethods[relativePath] = new List<string>();
publicMethods[relativePath].Add(action);
}
swaggerDoc.paths = swaggerDoc.paths.Where(pair => publicPaths.Contains(pair.Key))
.ToDictionary(pair => pair.Key,
pair => pair.Value);
return publicMethods;
}
private static void FilterByPublicActions(SwaggerDocument swaggerDoc, List<ApiDescription> publicApis, Dictionary<string, List<string>> publicMethods)
{
foreach (var api in publicApis)
{
var relativePath = ToRelativePath(api);
var availableActions = publicMethods[relativePath];
if (availableActions == null)
{
continue;
}
foreach (var path in swaggerDoc.paths.Where(pair => pair.Key.IndexOf(relativePath) > -1).ToList())
{
if (!availableActions.Contains("Get"))
path.Value.get = null;
if (!availableActions.Contains("Post"))
path.Value.post = null;
if (!availableActions.Contains("Put"))
path.Value.put = null;
if (!availableActions.Contains("Patch"))
path.Value.patch = null;
}
}
}
private static string ToRelativePath(ApiDescription apiDescription)
{
return "/" + apiDescription.RelativePath.Substring(0,apiDescription.RelativePath.LastIndexOf('/'));
}
}
最后，注册SwaggerConfig
public class SwaggerConfig
{
public static void Register()
{
var thisAssembly = typeof(SwaggerConfig).Assembly;
GlobalConfiguration.Configuration
.EnableSwagger(c =>
{
c.SingleApiVersion("v1", "Reports");
c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());
c.DocumentFilter<PublicApiFilter>();
})
.EnableSwaggerUi(c =>
{
});
}
}
例子
控制器
[PublicApi]
public class ProfileController : ApiController
方法
public class UserController : ApiController
{
[PublicApi]
public ResUsers Get(string sessionKey, int userId, int groupId) {
return Get(sessionKey, userId, groupId, 0);
}
如果你正在使用最小的API，你可以使用:
app.MapGet("/hello", () => "Hello World!").ExcludeFromDescription();
