指定 swagger 的示例请求 "Try it out"

Question

有没有办法指定 swagger 的示例请求？甚至多个？

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

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

为了

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

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

Answer 1

使用 ASP.NET Core 3.1、Swagger OAS 3 和 Swashbuckle.AspNetCore 5.4.1，以下模型 class + XML 评论对我有用：-

    /// <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; }
    }

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

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

Answer 2

在 .Net5 中，您可以在 Startup.cs

中将 SchemaFilter 添加到 Swagger

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

在 ExampleSchemaFilter.cs 中，您只需为特定的 class:

定义一个 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"),
            };
        }
    }
}

指定 swagger 的示例请求 "Try it out"

Specify example requests for swagger's "Try it out"

c#

asp.net-core-webapi

swagger-ui

swashbuckle.aspnetcore