Swashbuckle Swagger - Cách chú thích các loại nội dung?

Question

Làm cách nào để chú giải hành động ASP.NET WebAPI để siêu dữ liệu dao động bao gồm các loại nội dung mà tài nguyên của tôi hỗ trợ?

Cụ thể, tôi muốn tài liệu chứng minh rằng một trong các tài nguyên của tôi có thể trả về 'ban đầu' application/json và application/xml nhưng hiện cũng trả về định dạng mới, application/vnd.blah+json hoặc +xml.

Answer 1

Điều bạn cần làm là điều này; Swagger spec: bạn cần phải thêm phản ứng kiểu của bạn vào danh sách các câu trả lời-loại cho rằng hoạt động

"produces": [ 
      "application/json", 
      "text/json" 
      ], 

Điều này có thể được thực hiện với một OperationFilter

Pseudo Mã đến !!!

public class CustomResponseType : IOperationFilter 
{   
    public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription) 
    {    
      if (operation.operationId == "myCustomName") 
      { 
       operation.produces.Add("application/vnd.blah+json"); 
      }    
    }  
} 

có thể đặt OperationId thông qua chú thích [SwaggerOperation("myCustomName")].

Sau đó, áp dụng các operationsFilter trong swaggerConfig.cs

c.OperationFilter<CustomResponseType>(); 

Lưu ý: thay vì operation.operationId == "myCustomName" bạn có thể làm điều đó cho một lộ trình cụ thể hoặc bất cứ điều gì khác về cơ bản. ApiDescription cung cấp cho ALOT thông tin về ngữ cảnh.

Answer 2

Mở rộng @ VisualBean của câu trả lời

On phương pháp API của điều khiển bạn có thể sử dụng mã dưới đây để thiết lập một thuộc tính như:

[SwaggerResponseContentType(responseType:"application/pdf", Exclusive=true)] 
public HttpResponseMessage GetAuthorityForm(string id) 
{ 
.... 

Lưu ý: 'Độc quyền = true' sẽ loại bỏ tất cả các loại nội dung khác, nếu không, sử dụng Thuộc tính mới sẽ thêm Loại nội dung phản hồi mới trong menu thả xuống Giao diện người dùng chuyển đổi. Nó sẽ KHÔNG sửa đổi Bộ điều khiển hoặc API của bạn chỉ là tài liệu.

SwaggerConfig.cs

GlobalConfiguration.Configuration 
      .EnableSwagger(c => 
// Set filter to apply Custom Content Types to operations 
// 
c.OperationFilter<ResponseContentTypeOperationFilter>(); 

SwaggerReponseContentTypeAttribute.cs

/// <summary> 
/// SwaggerResponseContentTypeAttribute 
/// </summary> 
[AttributeUsage(AttributeTargets.Method)] 
public sealed class SwaggerResponseContentTypeAttribute : Attribute 
{ 
    /// <summary> 
    /// SwaggerResponseContentTypeAttribute 
    /// </summary> 
    /// <param name="responseType"></param> 
    public SwaggerResponseContentTypeAttribute(string responseType) 
    { 
     ResponseType = responseType; 
    } 
    /// <summary> 
    /// Response Content Type 
    /// </summary> 
    public string ResponseType { get; private set; } 

    /// <summary> 
    /// Remove all other Response Content Types 
    /// </summary> 
    public bool Exclusive { get; set; } 
} 

ResponseContentTypeOperationFilter.cs

public class ResponseContentTypeOperationFilter : IOperationFilter 
{ 
    public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription) 
    { 
     var requestAttributes = apiDescription.GetControllerAndActionAttributes<SwaggerResponseContentTypeAttribute>().FirstOrDefault(); 

     if (requestAttributes != null) 
     { 
      if (requestAttributes.Exclusive) 
       operation.produces.Clear(); 

      operation.produces.Add(requestAttributes.ResponseType); 
     } 
    } 
} 

Answer 3

Câu trả lời của @ OzBob giả định bạn chỉ muốn thêm một thuộc tính duy nhất vào một phương thức. Nếu bạn muốn thêm và ghi lại nhiều hơn một loại nội dung cho cùng một phương pháp bạn có thể sử dụng như sau:

SwaggerReponseContentTypeAttribute.cs

/// <summary> 
/// SwaggerResponseContentTypeAttribute 
/// </summary> 
[AttributeUsage(AttributeTargets.Method, AllowMultiple = true)] 
public class SwaggerResponseContentTypeAttribute : Attribute 
{ 
    /// <summary> 
    /// SwaggerResponseContentTypeAttribute 
    /// </summary> 
    /// <param name="responseType"></param> 
    public SwaggerResponseContentTypeAttribute(string responseType) 
    { 
     ResponseType = responseType; 
    } 
    /// <summary> 
    /// Response Content Type 
    /// </summary> 
    public string ResponseType { get; private set; } 

    /// <summary> 
    /// Remove all other Response Content Types 
    /// </summary> 
    public bool Exclusive { get; set; } 
} 

ResponseContentTypeOperationFilter.cs

public class ResponseContentTypeOperationFilter : IOperationFilter 
{ 
    public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription) 
    { 
     var requestAttributes = apiDescription.GetControllerAndActionAttributes<SwaggerResponseContentTypeAttribute>(); 

     foreach (var requestAttribute in requestAttributes) 
     { 
      if (requestAttribute.Exclusive) 
      { 
       operation.produces.Clear(); 
      } 
      operation.produces.Add(requestAttribute.ResponseType); 
     } 
    } 
} 

Lưu ý rằng khi bạn có nhiều thuộc tính trên cùng một phương pháp và bạn muốn thay thế các loại nội dung hiện có, bạn nên đặt Exclusive = true trên chỉ thuộc tính đầu tiên. Nếu không, bạn sẽ không nhận được tất cả các thuộc tính vào tài liệu.