Mô tả tham số Swashbuckle

Question

Tôi đang sử dụng thuộc tính SwaggerResponse để trang trí các thao tác điều khiển api của tôi, tất cả đều hoạt động tốt, tuy nhiên khi tôi xem tài liệu được tạo, trường mô tả cho tham số trống.

Có cách tiếp cận dựa trên thuộc tính để mô tả các thông số hành động (thay vì nhận xét XML) không?

Answer 1

Với Swashbuckle mới nhất, hay nói đúng hơn ít nhất Swashbuckle.AspNetCore variant mà tôi đang sử dụng, trường mô tả cho tham số bây giờ có thể được hiển thị chính xác dưới dạng đầu ra.

Nó đòi hỏi các điều kiện sau được đáp ứng:

• XML comments phải được bật và cấu hình với Swagger
• thông số nên được trang trí một cách rõ ràng với một trong hai [FromRoute], [FromQuery], [FromBody] hoặc [FromUri]
• cùng cho các loại phương pháp (có/bài/đặt vv), mà nên được trang trí với [Http...]
• Mô tả các thông số như bình thường với một bình luận <param ...> xml

Một mẫu đầy đủ trông như thế này:

/// <summary> 
/// Short, descriptive title of the operation 
/// </summary> 
/// <remarks> 
/// More elaborate description 
/// </remarks> 
/// <param name="id">Here is the description for ID.</param> 
[ProducesResponseType(typeof(Bar), (int)HttpStatusCode.OK)] 
[HttpGet, Route("{id}", Name = "GetFoo")] 
public async Task<IActionResult> Foo([FromRoute] long id) 
{ 
    var response = new Bar(); 
    return Ok(response); 
} 

nào xuất ra như sau:

Answer 2

Bạn nên xác nhận rằng bạn đang cho phép Swagger để sử dụng XML bình luận

httpConfig.EnableSwagger(c => { 
       if (GetXmlCommentsPath() != null) { 
        c.IncludeXmlComments(GetXmlCommentsPath()); 
       } 
... 
... 
); 

protected static string GetXmlCommentsPath() { 
    var path = HostingEnvironment.MapPath("path to your xml doc file"); 
    return path; 
} 

Bạn cũng nên kiểm tra xem bạn đang tạo ra XML doc cho dự án của bạn mong muốn. Theo dự án của bạn mong muốn Thuộc tính (Alt + Enter trên đầu trang của dự án hoặc Right Click -> Properties) ->Build -> Kiểm tra tập tin tài liệu XML

Answer 3

Đối với đầy đủ sake, khi sử dụng phiên bản mới nhất của Swashbuckle.AspNetCore (2.1.0) và Swashbuckle.SwaggerGen/Ui (6.0.0), cho phép Xml tạo tệp tài liệu trong dự án của bạn Xây dựng

Sau đó, theo phương thức ConfigureServices():

services.ConfigureSwaggerGen(options => 
{ 
    options.SingleApiVersion(new Info 
    { 
     Version = "v1", 
     Title = "My API", 
     Description = "API Description" 
    }); 
    options.DescribeAllEnumsAsStrings(); 

    var xmlDocFile = Path.Combine(AppContext.BaseDirectory, $"{_hostingEnv.ApplicationName}.xml"); 
    if (File.Exists(xmlDocFile)) 
    { 
     var comments = new XPathDocument(xmlDocFile); 
     options.OperationFilter<XmlCommentsOperationFilter>(comments); 
     options.ModelFilter<XmlCommentsModelFilter>(comments); 
    } 
});