SwashBuckle Swagger-UI示例请求用于具有FromQuery属性的HTTP GET方法

ijnw1ujt  于 2023-04-30  发布在  其他
关注(0)|答案(2)|浏览(261)

我已经成功地将示例添加到我的Web API中,使用SwashBuckle.AspNetCoreSwashbuckle.AspNetCore.Filters进行POST方法:

DTO

public class ExampleDTO
{
    public string MyFoo { get; set; }
}

请求示例

public class ExampleDTOExample : IExamplesProvider<ExampleDTO>
{
    public ExampleDTO GetExamples()
    {
        return new ExampleDTO()
        {
            MyFoo = "bar"
        };
    }
}

控制器方式

[SwaggerOperation(
    Summary = "...",
    Description = "...",
    OperationId = "PostFoo"
)]
[SwaggerResponse(200, "Returns ...", typeof(int))]
[HttpPost]
[Route("post-foo")]
public ActionResult<int> PostFoo([FromBody]ExampleDTO request)
{
    throw new NotImplementedException();
}

这工作非常好。当我单击“tryitout”按钮时,我将“bar”作为属性foo的预填充值。
然而,当我试图对GET请求做同样的事情时,e。例如,对于这样的查询中的参数,文本框不会预先填充值“bar”:

public class ExampleDTO
{
    [FromQuery(Name = "foo")]
    public string MyFoo { get; set; }
}

控制器方式

[SwaggerOperation(
    Summary = "...",
    Description = "...",
    OperationId = "GetFoo"
)]
[SwaggerResponse(200, "Returns ...", typeof(int))]
[HttpGet]
[Route("get-foo")]
public ActionResult<int> GetFoo([FromQuery]ExampleDTO request)
{
    throw new NotImplementedException();
}

如何强制文本框预先填充示例值?到目前为止,我已经找到了一个解决方案,指定一个默认值,这不是我想要的。我只想在Swagger UI中使用默认值的属性。

ldioqlga

ldioqlga1#

如果我没记错的话,你看到的价值是:

这不是示例,而是默认值。
这是我过去做过的事情:

"/attrib/{payId}": {
    "get": {
        "tags": [
            "Attribute"
        ],
        "operationId": "Attribute_Get",
        "consumes": [],
        "produces": [
            "application/json",
            "text/json",
            "text/html"
        ],
        "parameters": [
            {
                "name": "payId",
                "in": "path",
                "required": true,
                "type": "integer",
                "format": "int32",
                "default": 123
            }
        ]

www.example. com

下面是另一个既有默认又有示例的案例

"Company": {
    "required": [
        "Id",
        "MyId"
    ],
    "properties": {
        "Id": {
            "description": "The Unique Company ID",
            "example": "123",
            "type": "integer",
            "format": "int32",
            "default": 456
        },
        "MyId": {
            "example": 123,
            "type": "integer",
            "format": "int32"
        },

http://swagger-net-test.azurewebsites.net/swagger/ui/index#/Company/Company_Get2
您可以看到该示例与SwaggerUI中显示的示例不同

7vux5j2d

7vux5j2d2#

您可以使用XML注解来实现此目的。
自2018年5月以来,Swashbuckle。AspNetCore支持通过XML注解添加示例。
资料来源: www.example.com
但首先,您需要为项目启用XMLDocumentation file。您可以在项目的属性中启用它。

之后,您必须在Startup中包含对Swagger的XML注解。cs

public void ConfigureServices(IServiceCollection services)
{
    ...

    services.AddSwaggerGen(c =>
    {
        ...

        // This path can be different on your project.
        var filePath = Path.Combine(AppContext.BaseDirectory, "WebApi.xml");
        c.IncludeXmlComments(filePath);

        ...

    });

    ...
}

之后,必须将XML示例添加到DTO的属性中

public class ExampleDTO
{
    /// <example> MyFooExampleValue </example>
    public string MyFoo { get; set; }
}

结果如下:

“Try it out”的结果:

注意:不仅在DTO中,还可以直接向API写入XML注解
很快(2020年4月,曾经是我的Swashbuckle。AspNetCore PR已经发布)你也可以在查询字符串上添加原始类型的示例,例如。g的。

/// <param name="id" example="123">The product id</param>
[HttpGet("{id}")]
public Product GetById(int id)

有关更多信息,您可以访问以下链接:
Using XML Comments As Web API Documentation With Swagger
请求Swashbuckle的示例。AspNetCore.Filters

相关问题