web-dev-qa-db-ja.com

「リクエストとレスポンスモデル」にSwaggerコメントをどのように追加しますか？

以下の例のようなメソッドにコメントを追加できますが、要求および応答モデルにコメントを追加するのはどうですか？

/// <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>
c#asp.net-coreswaggerswashbuckle
3
001

はい、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; }
    }
}

そして、次のようになります： enter image description here

8
Helder Sepulveda

それが正確にあなたが話していることであるかどうかはわかりませんが、このようなさまざまな応答にコメントを追加することができます

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

これは、コントローラーメソッドを装飾するために使用する属性です。

1
Dimitar Tsonev

私は.netcore 3.0を使用しているので、@ Helderの応答に加えて、XMLコメントを表示するためにさらに2つの手順を実行する必要がありました。

プロジェクトファイルを手動で編集します。

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

詳細はこちら

1
Dinch