如何在WebAPI应用程序的Swagger UI中添加方法描述 [英] How to add method description in Swagger UI in WebAPI Application

问题描述

我正在使用Swagger作为我的API工具框架，到目前为止效果很好.我刚刚碰到此页面 https://petstore.swagger.io/

I am using Swagger as my API tooling framework and it is working out great so far. I just came across this page https://petstore.swagger.io/

并查看了每种方法的描述.例如

and saw how each method has a description. For example,

POST:宠物/是通过向商店添加新的Pet 来描述的.我以为添加 [Description("Description text")] 之类的东西应该可以，但事实并非如此.我该如何实现?

POST: pet/ is described by add a new Pet to the store. I thought adding something like [Description("Description text")] should do it but it just does not. How can I achieve this?

推荐答案

在项目中已对此进行了详细记录: https://github.com/domaindrivendev/Swashbuckle.AspNetCore#include-descriptions-from-xml-comments

This is well documented in the project: https://github.com/domaindrivendev/Swashbuckle.AspNetCore#include-descriptions-from-xml-comments

要使用易于理解的描述增强生成的文档，可以使用

To enhance the generated docs with human-friendly descriptions, you can annotate controller actions and models with Xml Comments and configure Swashbuckle to incorporate those comments into the outputted Swagger JSON:

1-打开项目的属性"对话框，单击构建"选项卡，并确保已选中"XML文档文件".这样会在构建时生成一个包含所有XML注释的文件.

1 - Open the Properties dialog for your project, click the "Build" tab and ensure that "XML documentation file" is checked. This will produce a file containing all XML comments at build-time.

这时，任何未使用XML注释注释的类或方法都将触发生成警告.要抑制这种情况，请在属性对话框的禁止警告"字段中输入警告代码"1591".

2-配置Swashbuckle将文件中的XML注释合并到生成的Swagger JSON中:

2 - Configure Swashbuckle to incorporate the XML comments on file into the generated Swagger JSON:

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1",
        new Info
        {
            Title = "My API - V1",
            Version = "v1"
        }
     );

     var filePath = Path.Combine(System.AppContext.BaseDirectory, "MyApi.xml");
     c.IncludeXmlComments(filePath);
}

3-用摘要，备注和响应标签注释您的操作:

3 - Annotate your actions with summary, remarks and response tags:

/// <summary>
/// Retrieves a specific product by unique id
/// </summary>
/// <remarks>Awesomeness!</remarks>
/// <response code="200">Product created</response>
/// <response code="400">Product has missing/invalid values</response>
/// <response code="500">Oops! Can't create your product right now</response>
[HttpGet("{id}")]
[ProducesResponseType(typeof(Product), 200)]
[ProducesResponseType(typeof(IDictionary<string, string>), 400)]
[ProducesResponseType(500)]
public Product GetById(int id)

4-您还可以使用摘要标记和示例标记来注释类型:

4 - You can also annotate types with summary and example tags:

public class Product
{
    /// <summary>
    /// The name of the product
    /// </summary>
    /// <example>Men's basketball shoes</example>
    public string Name { get; set; }

    /// <summary>
    /// Quantity left in stock
    /// </summary>
    /// <example>10</example>
    public int AvailableStock { get; set; }
}

5-重建项目以更新XML Comments文件并导航到Swagger JSON端点.请注意如何将描述映射到相应的Swagger字段.

5 - Rebuild your project to update the XML Comments file and navigate to the Swagger JSON endpoint. Note how the descriptions are mapped onto corresponding Swagger fields.

注意:您还可以通过使用摘要标记注释API模型及其属性来提供Swagger Schema描述.如果您有多个XML注释文件(例如，用于控制器和模型的单独的库)，则可以多次调用IncludeXmlComments方法，它们都将合并到输出的Swagger JSON中.

仔细按照说明进行操作，您应该得到类似于以下内容的内容:
https://swashbucklenetcore.azurewebsites.net/swagger/

Following the instructions carefully you should get something that looks like:
https://swashbucklenetcore.azurewebsites.net/swagger/

这篇关于如何在WebAPI应用程序的Swagger UI中添加方法描述的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！