如何在“请求和响应模型”中添加一个 Swagger 的评论?

ttcibm8c  于 2023-03-18  发布在  其他
关注(0)|答案(5)|浏览(124)

您可以像下面的示例那样在方法上添加注解,但是向请求和响应模型添加注解怎么样呢?

/// <summary>
/// my summary
/// </summary>
/// <remarks>
/// remark goes here.
/// </remarks>
/// <param name="somepara">Required parameter: Example: </param>
/// <return>Returns comment</return>
/// <response code="200">Ok</response>
7uhlpewt

7uhlpewt1#

是的,正如Dimitar所说,您可以使用SwaggerResponse向响应添加注解,请求稍有不同,就像您向操作添加xml注解一样,您应该向参数添加注解,以下是一个示例:

using Swagger.Net.Annotations;
using System;
using System.Collections.Generic;
using System.Net;
using System.Web.Http;
using System.Web.Http.Results;

namespace Swagger_Test.Controllers
{
    public class IHttpActionResultController : ApiController
    {

        [SwaggerResponse(HttpStatusCode.OK, "List of customers", typeof(IEnumerable<int>))]
        [SwaggerResponse(HttpStatusCode.NotFound, Type = typeof(NotFoundResult))]
        public IHttpActionResult Post(MyData data)
        {
            throw new NotImplementedException();
        }
    }

    /// <summary>My super duper data</summary>
    public class MyData
    {
        /// <summary>The unique identifier</summary>
        public int id { get; set; }

        /// <summary>Everyone needs a name</summary>
        public string name { get; set; }
    }
}

swagger 地看起来就像:

yacmzcpb

yacmzcpb2#

我使用的是.net core 3.0,所以除了@Helder的响应之外,我还必须执行以下两个步骤来使XML注解可见。
手动编辑项目文件。

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

将以下内容添加到startup.cs服务配置方法中。

services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new OpenApiInfo
                {
                    Title = "My Good API",
                    Version = "v1",
                    Description = "Doesn't hurt to add some description."
                });

                // Set the comments path for the Swagger JSON and UI.
                var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
                c.IncludeXmlComments(xmlPath);
            });

从微软的斯瓦格文档
可以通过以下方法启用XML注解:

  • 手动将突出显示的行添加到.csproj文件中:

启用XML注解可为未记录的公共类型和成员提供调试信息。未记录的类型和成员由警告消息指示。例如,以下消息指示违反警告代码1591:

tez616oj

tez616oj3#

我不确定这是否正是您所谈论的内容,但您可以对不同的回答添加评论,如下图所示

[SwaggerResponse(HttpStatusCode.Unauthorized, "Authorization has been denied for this request")]

这是用来修饰控制器方法的属性。

44u64gxh

44u64gxh4#

对于那些没有找到现有答案的人,请确保您的属性类所在的项目也启用了xml文档。
在我的例子中,我的DTO有一个单独的项目,并且也需要将它添加到其中。请确保在使用另一个IncludeXmlComments方法时也包含来自该项目的xml注解。

ua4mk5z4

ua4mk5z45#

也可以添加不带xml的注解

//program.cs
    builder.Services.AddSwaggerGen(c =>
    {
        c.EnableAnnotations();
    });

    using Swashbuckle.AspNetCore.Annotations; 

    //inside model class
    [SwaggerSchema(Description = "My super duper data")] 
    public int Id { get; set; }

    //in controller
    [SwaggerOperation(Summary = "My controller")]
    public IHttpActionResult Post(MyData data)
    {
        throw new NotImplementedException();
    }

相关问题