未显示Swagger响应描述

gmxoilav  于 2022-11-06  发布在  其他
关注(0)|答案(3)|浏览(284)

我目前正试图在Swagger UI中显示一个特定响应的描述,但似乎没有一个文档真正涵盖了这方面的所有方面,而且我从Get started with Swashbuckle and ASP.NET Core中尝试的所有示例在.NET Core 3.1中都不起作用...

/// <summary>
        /// Test route...
        /// </summary>
        /// <returns></returns>
        /// <response code="200">This is a test</response>
        [HttpGet]
        [ProducesResponseType(typeof(string), StatusCodes.Status200OK)]
        public IActionResult Get()
        {
            return Ok("Hello World");
        }

My .csproj还包含以下内容:

<PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);1591</NoWarn>
  </PropertyGroup>

Swagger UI最终看起来是这样的(正如您所看到的,“Descriptipn”列不包含“This is a test”文本,而它可能应该包含)。

我还添加了[SwaggerResponse(StatusCodes.Status200OK, ...)],但没有任何变化。

jchrr9hc

jchrr9hc1#

事实证明,[SwaggerResponse]工作正常,但在此之前,我需要在我的启动中“启用注解”...

services.AddSwaggerGen(config =>
    {
        config.SwaggerDoc("v1", new OpenApiInfo
        {
            Title = "Some API",
            Version = "v1"
        });

        config.EnableAnnotations();
    });
41ik7eoe

41ik7eoe2#

自.NET v6以来,有两种管理API的方法:经典的API控制器和minimal API。它们是非常不同的,所以我在下面提供两个答案。

适用于经典/传统API控制器

根据官方文档,这是通过XML注解与ProducesResponseType属性的组合完成的:

<response code="201">This is a test</response>
[ProducesResponseType(StatusCodes.Status201Created)]

评论需要链接到Swagger

builder.Services.AddSwaggerGen(options =>
{
    // using System.Reflection;
    var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));
});

对于最小API

今天,最小的API仍然是相当原始的与补丁支持都NSwag和Swashbuckle。
this post on SO中,建议使用传统的属性:

app.MapGet("/clients",
    [SwaggerOperation(
        Summary = "returns clients",
        Description = "more description on get `clients`")]
    [SwaggerResponse(200, "success")]
    [SwaggerResponse(500, "some failure")]
    async (IClientRepository repo) =>
    {
        var results = await repo.GetClientsAsync();
        return mapper.Map<IEnumerable<ClientModel>>(results);
    }).WithTags("Clients");
7rtdyuoh

7rtdyuoh3#

在您的项目属性中,您应该检查刀片Build下找到的Output XML documentation file。然后在您的startup文件中:

services.AddSwaggerGen(c =>
{
    //rest of your code

    //i'm using the default path generated, but you can adjust it as you want
    var XMLPath = AppDomain.CurrentDomain.BaseDirectory + nameof(MyNamespace) + ".xml";
    if (File.Exists(XMLPath))
    {
        c.IncludeXmlComments(XMLPath);
    }
});

如果仍然不起作用,请检查xml文件是否出现在bin文件夹中。如果没有,请检查Visual Studio中的属性,并将Copy to output directory调整为CopyCopy if newer

相关问题