Swashbuckle.AspNetCore <example> 不适合我

Question

我正在尝试使用标签设置示例，但是它对我不起作用。我正在使用

Swashbuckle.AspNetCore

库。

下面是一些代码示例，

1. 将以下内容添加到我的 csproj.文件

<GenerateDocumentationFile>true</GenerateDocumentationFile>

2. 程序.cs

            builder.Services.AddSwaggerGen(options =>
            {
                options.OperationFilter<SwaggerDefaultValues>();
                var filePath = Path.Combine(System.AppContext.BaseDirectory, "My.xml");
                options.IncludeXmlComments(filePath);

            });

3. 控制器看起来像，

[Authorize]
[ApiController]
[ApiVersion("1.0")]
[Route("[controller]")]
[Route("v{version:apiVersion}/[controller]")]
[Produces("application/json")]
public class MyController : ControllerBase
{
}

4. 我的方法看起来像，

/// <summary>
    /// Method to Post an Incident
    /// </summary>
    /// <param name="initiateRequest" example="FORM_CODE"></param>
    [ProducesResponseType(typeof(InitiateResponseDTO), StatusCodes.Status201Created)]
    [ProducesResponseType(typeof(ExceptionDetails), StatusCodes.Status400BadRequest)]
    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
    [ProducesResponseType(StatusCodes.Status500InternalServerError)]
    [HttpPost]
public async Task<ActionResult<InitiateResponseDTO>> PostAsync(MyRequest myRequest)
    {
//Logic

        return StatusCode(StatusCodes.Status201Created, InitiateResponseDTO);
    }

5. MyDTO 看起来像，

/// <summary>
/// Initiate Response DTO
/// </summary>
public class InitiateResponseDTO
{
    /// <summary>
    /// IncidentId 
    /// </summary>
    /// <example>985769890</example>
    public int IncidentId { get; set; }
}

6. 异常详细信息类

/// <summary>
    /// Exception Details class
    /// </summary>
    public class ExceptionDetails
    {
        /// <summary>
        /// HTTP status code for the exception.
        /// </summary>
        /// <example>400</example>
        public int StatusCode { get; set; } = (int)HttpStatusCode.InternalServerError;

        /// <summary>
        /// (Friendly) message about the exception.
        /// </summary>
        /// <example>Invalid form code supplied: FORM_CODE</example>
        public string Message { get; set; } = "An error occured";

        /// <summary>
        /// Error code for the returned error.
        /// </summary>
        /// <example>UNKNOWN_FORM</example>
        public string ErrorCode { get; set; } = ErrorCodes.Generic;

        /// <summary>
        /// Exception Target denoting the method in which the error occurred.
        /// </summary>
        /// <example>MoveNext <- Method name from which the error occurred</example>
        public string? Target { get; set; }

        /// <summary>
        /// InnerError message denoting the StackTrace.
        /// </summary>
        /// <example> Some Sample</example>
public string? InnerError { get; set; }
}

仍然在 Swagger UI 中，我没有看到示例值，

配置有什么不正确的地方吗？我正在使用

Swashbuckle.AspNetCore

6.4.0

Answer 1

一个简单的选择是用 [DefaultValue] 来装饰你的属性

/// <summary>
/// Initiate Response DTO
/// </summary>
public class InitiateResponseDTO
{
    /// <summary>
    /// IncidentId 
    /// </summary>
    /// <example>985769890</example>
    [DefaultValue(985769890)]
    public int IncidentId { get; set; }
}

根据您的项目中序列化的方式，它应该可以工作。

还可以查看 Swashbuckle.AspNetCore.Filters Nuget 库来根据需要设置示例，但这需要更多工作：https://github.com/mattfrear/Swashbuckle.AspNetCore.Filters#automatic-注释

Answer 2

添加您可以使用的操作示例 添加您的示例。

/// <summary>
/// Description
/// </summary>
/// <param name="model"></param>
/// <returns></returns>
/// <remarks>
/// Sample Request :
/// </remarks>
public IActionResult Add(AddDto model)
{
   return Ok();
}