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

Question

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

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

• 创建订单命令
• ShipOrderCommand
• GetOrderByIdQuery
• GetUnshippedOrdersForCurrentCustomerQuery

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

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

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

但由于没有 Controller ，我无法在 Swashbuckle 中引导它；阅读文档后，我没有找到在 Swashbuckle 中注册这些类型的 url 的方法。有没有办法配置 Swashbuckle，使其仍然可以输出 API 文档？

为了完整起见，可以在 here 中找到演示这一点的引用架构应用程序.

Answer 1

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

您首先需要创建并注册自定义 IApiExplorer。这是 Swashbuckle 用来获取 API 描述的接口(interface)，它负责探索所有 Controller 和操作以收集所需信息。我们基本上将使用代码扩展现有的 ApiExplorer，以探索我们的消息类并从中构建 api 描述。界面本身很简单:

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

Api描述类包含了API操作的各种信息，是Swashbuckle用来搭建swagger ui页面的。它有一个有问题的属性:ActionDescriptor。它代表 asp.net mvc Action ，我们没有 Action ，也没有 Controller 。您可以使用它的假实现，或者模仿 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 将调用的覆盖，如果我们不为它们提供值，它们将失败。

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

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 界面中看到我们的自定义消息命令: