Question

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

例如，我们有以下消息：

CreateOrderCommand
ShipOrderCommand
GetOrderByIdQuery
GetUnshippedOrdersForCurrentCustomerQuery

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

API /命令/ CreateOrder
API /命令/运送订单
API /查询/ GetOrderById
API /查询/ GetUnshippedOrdersForCurrentCustomer

可以想象，这种使用Web API的方式简化了开发并提高了开发性能;编写的代码更少，测试的代码更少。

但由于没有控制器，我在Swashbuckle中引导这个问题很困难;阅读完文档后，我找不到在Swashbuckle中注册这些网址的方法。有没有办法以这样的方式配置Swashbuckle它仍然可以输出API文档？

为了完整起见，可以找到演示此内容的参考架构应用程序here。

Answer 1

似乎Swashbuckle不支持开箱即用，但您可以扩展它以达到预期的效果，同时仍然重用大部分的swagger基础架构。可能需要花费一些时间和精力，一般情况下并不多，但对于我来说，在这个答案中提供完整的解决方案太过分了。但是我会尝试至少让你开始。请注意，下面的所有代码都不会很干净，生产就绪。

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

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

Api描述类包含有关api操作的各种信息，它是Swashbuckle用来构建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会调用的一些覆盖，如果我们没有为它们提供值，它们将会失败。

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

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作为消息调度程序

1 个答案: