为 swagger 的“试用”指定示例请求答案

【问题标题】：Specify example requests for swagger's "Try it out"为 swagger 的“试用”指定示例请求
【发布时间】：2019-07-26 08:25:44
【问题描述】：

有没有办法为 swagger 指定示例请求？甚至可能是多个？

Try it out 按钮仅显示通用值，例如：

{
    "firstName": "string",
    "lastName": "string"
}

为

public class User
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
}

当您必须首先编辑所有值时，使用大型对象变得非常困难。我知道我可以使用 Postman，我也可以，但是能够使用 swagger 创建多个好看且有用的示例将非常好。

【问题讨论】：

@ArtemIgnatovich 不，不是这个。我正在寻找示例/测试值，并且可能有多个尝试 API 的请求。设置默认值是简单的，它们不是一回事。
我之前没听说过这个功能。 @t3chb0t 现在很清楚你的意思了。您可以使用带有格式化数据的示例呈现一个部分（使用纯 html）（将其复制并粘贴到试用窗口中），但我认为在“试用”部分是不可能的。
另一个尝试的选择是研究一个内置插件系统，用于 swagger-ui 或已经存在的公共扩展（还有一个空间可以编写你自己的并在 github 上获得一些星星 he-he )。
@ArtemIgnatovich 我想我找到了，请参阅请求正文示例 here
看看这是否有帮助：github.com/mattfrear/…

标签： c# asp.net-core-webapi swagger-ui swashbuckle.aspnetcore

【解决方案1】：

使用 ASP.NET Core 3.1、Swagger OAS 3 和 Swashbuckle.AspNetCore 5.4.1，以下模型类 + XML cmets 适合我：-

    /// <summary>
    /// A user.
    /// </summary>
    public class User
    {
        /// <summary>
        /// The user's first name.
        /// </summary>
        /// <example>Jane</example>
        public string FirstName { get; set; }

        /// <summary>
        /// The user's last name.
        /// </summary>
        /// <example>Austin</example>
        public string LastName { get; set; }
    }

现在，当我单击“试用”时（对于在消息正文中采用 User 模型的 POST 操作），我得到默认值：-

{
    "firstName": "Jane",
    "lastName": "Austin"
}

【讨论】：

我目前无法试用，但这是否意味着 Swagger 可以读取评论的example 元素？
我不确定是 Swagger 还是 Swashbuckle 在这里工作（或者他们两者都是），但基本上是的：它正在读取 <example> XML 注释并将该值用作默认值做“试试看”的时候。
@AndrewWebb 我昨天发布了同样要求的问题，我的问题已链接到这里，我得到了你的答案。如果所有相关技术与我的应用程序中提到的相同，我也尝试过这样做。是否需要任何配置，或者您可以进一步分享查看此内容所需的其他内容。
@Monibrata 如果类型在不同的项目中，请确保您正在输出该项目的 XML 文档，并将文件添加到 SwaggerGenOptions 中的 IncludeXmlComments 参见stackoverflow.com/a/50837958/914352

【解决方案2】：

在 .Net5 中，您可以在 Startup.cs 中将 SchemaFilter 添加到 Swagger

public override void ConfigureServices(IServiceCollection services)
{
    services.AddSwaggerGen(c =>
    {
        c.SchemaFilter<ExampleSchemaFilter>();
    });
}

在 ExampleSchemaFilter.cs 中，您只需为特定类定义一个 OpenApiObject：

using Microsoft.OpenApi.Any;
using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;

public class ExampleSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        if (context.Type == typeof(User))
        {
            schema.Example = new OpenApiObject()
            {
                ["firstName"] = new OpenApiString("John"),
                ["lastName"] = new OpenApiString("Doe"),
            };
        }
    }
}

【讨论】：