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

1 回答

• 9

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

  

  回复于 2024-05-03T11:58:02+08:00