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

Posted 2023-03-31

【中文标题】为 swagger 的“试用”指定示例请求

【英文标题】：Specify example requests for swagger's "Try it out"

【发布时间】：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/…

【参考方案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 参见***.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"),
            ;