使用 DelegatingHandler 配置 Swashbuckle 作为消息调度程序

Question

我有一个 Web API，它是一个非常薄的基础架构，只包含两个 DelegatingHandler 实现，这些实现将传入消息分派到业务中定义的消息处理程序实现层。这意味着没有控制器，也没有控制器操作； API 仅根据消息定义。这意味着在实施新功能时不需要更改此基础架构层中的代码。

例如，我们有这样的消息：

创建订单命令
ShipOrderCommand
GetOrderByIdQuery
GetUnshippedOrdersForCurrentCustomerQuery

委托处理程序根据 url 确定确切的消息，并将请求内容反序列化为该消息类型的实例，之后将该消息转发给适当的消息处理程序。例如，这些消息（当前）映射到以下 urls:

api/commands/CreateOrder
api/commands/ShipOrder
api/queries/GetOrderById
api/queries/GetUnshippedOrdersForCurrentCustomer

如您所想，这种使用 Web 的方式 API 简化了开发并提高了开发性能；要编写的代码和要测试的代码更少。

但是由于没有控制器，我在 Swashbuckle 中启动它时遇到了麻烦；阅读文档后，我没有找到在 Swashbuckle 中注册这些类型的 url 的方法。有没有办法配置 Swashbuckle，使其仍然可以输出 API 文档？

为了完整起见，可以在 here.

中找到演示这一点的参考架构应用程序

Answer 1

Swashbuckle 似乎不支持这种开箱即用的功能，但您可以对其进行扩展以获得所需的结果，同时仍然重用大部分 swagger 基础设施。虽然可能需要一些时间和精力，但一般来说并不多，但我无法在此答案中提供完整的解决方案。但是，我会尝试至少让您入门。请注意，下面的所有代码都不会很干净，也不会准备好生产。

您首先需要创建并注册自定义 IApiExplorer。这是 Swashbuckle 用于获取您的 api 描述的接口，它负责探索所有控制器和操作以收集 required 信息。我们基本上将使用代码扩展现有的 ApiExplorer，以从中探索我们的消息 classes 和 build api 描述。界面本身很简单：

public interface IApiExplorer
{    
    Collection<ApiDescription> ApiDescriptions { get; }
}

Api 描述 class 包含有关 api 操作的各种信息，它是 Swashbuckle 用于 build swagger ui 页面的内容。它有一个问题属性：ActionDescriptor。它代表 asp.net mvc 动作，我们没有动作，也没有控制器。您可以使用它的假实现，或者模仿 asp.net HttpActionDescriptor 的行为并提供真实值。为简单起见，我们将采用第一条路线：

class DummyActionDescriptor : HttpActionDescriptor {
    public DummyActionDescriptor(Type messageType, Type returnType) {
        this.ControllerDescriptor = new DummyControllerDescriptor() {
            ControllerName = "Message Handlers"
        };
        this.ActionName = messageType.Name;
        this.ReturnType = returnType;
    }

    public override Collection<HttpParameterDescriptor> GetParameters() {
        // note you might provide properties of your message class and HttpParameterDescriptor here
        return new Collection<HttpParameterDescriptor>();
    }

   public override string ActionName { get; }
   public override Type ReturnType { get; }

    public override Task<object> ExecuteAsync(HttpControllerContext controllerContext, IDictionary<string, object> arguments, CancellationToken cancellationToken) {
        // will never be called by swagger
        throw new NotSupportedException();
    }
}

class DummyControllerDescriptor : HttpControllerDescriptor {
    public override Collection<T> GetCustomAttributes<T>() {
         // note you might provide some asp.net attributes here
        return new Collection<T>();
    }
}

这里我们只提供一些 swagger 将调用的覆盖，如果我们不为它们提供值，它们将失败。

现在让我们定义一些属性来装饰消息classes：

class MessageAttribute : Attribute {
    public string Url { get; }
    public string Description { get; }
    public MessageAttribute(string url, string description = null) {
        Url = url;
        Description = description;
    }
}

class RespondsWithAttribute : Attribute {
    public Type Type { get; }
    public RespondsWithAttribute(Type type) {
        Type = type;
    }
}

还有一些消息：

abstract class BaseMessage {

}

[Message("/api/commands/CreateOrder", "This command creates new order")]
[RespondsWith(typeof(CreateOrderResponse))]
class CreateOrderCommand : BaseMessage {

}

class CreateOrderResponse {   
    public long OrderID { get; set; }
    public string Description { get; set; }
}

现在自定义 ApiExplorer：

class MessageHandlerApiExplorer : IApiExplorer {
    private readonly ApiExplorer _proxy;

    public MessageHandlerApiExplorer() {
        _proxy = new ApiExplorer(GlobalConfiguration.Configuration);
        _descriptions = new Lazy<Collection<ApiDescription>>(GetDescriptions, true);
    }

    private readonly Lazy<Collection<ApiDescription>> _descriptions;

    private Collection<ApiDescription> GetDescriptions() {
        var desc = _proxy.ApiDescriptions;
        foreach (var handlerDesc in ReadDescriptionsFromHandlers()) {
            desc.Add(handlerDesc);
        }
        return desc;
    }

    public Collection<ApiDescription> ApiDescriptions => _descriptions.Value;

    private IEnumerable<ApiDescription> ReadDescriptionsFromHandlers() {
        foreach (var msg in Assembly.GetExecutingAssembly().GetTypes().Where(c => typeof(BaseMessage).IsAssignableFrom(c))) {
            var urlAttr = msg.GetCustomAttribute<MessageAttribute>();
            var respondsWith = msg.GetCustomAttribute<RespondsWithAttribute>();
            if (urlAttr != null && respondsWith != null) {
                var desc = new ApiDescription() {
                    HttpMethod = HttpMethod.Get, // grab it from some attribute
                    RelativePath = urlAttr.Url,
                    Documentation = urlAttr.Description,
                    ActionDescriptor = new DummyActionDescriptor(msg, respondsWith.Type)
                };                    

                var response = new ResponseDescription() {
                    DeclaredType = respondsWith.Type,
                    ResponseType = respondsWith.Type,
                    Documentation = "This is some response documentation you grabbed from some other attribute"
                };                    
                desc.GetType().GetProperty(nameof(desc.ResponseDescription)).GetSetMethod(true).Invoke(desc, new object[] {response});
                yield return desc;
            }
        }
    }
}

最后注册 IApiExplorer（在注册 Swagger 后）：

GlobalConfiguration.Configuration.Services.Replace(typeof(IApiExplorer), new MessageHandlerApiExplorer());

完成所有这些后，我们可以在 swagger 界面中看到我们的自定义消息命令：

使用 DelegatingHandler 配置 Swashbuckle 作为消息调度程序

Configuring Swashbuckle With DelegatingHandler as message dispatcher

c#

asp.net-web-api

swagger

swashbuckle