web-dev-qa-db-ja.com

SwaggerにAPIから返されたオブジェクトの例を表示させる方法は？

初めてAPIのセットを作成しています。メソッドの1つを次に示します。

    // GET: api/Doors/0
    /// <summary>
    /// Get a list of all doors for a given organization.
    /// </summary>
    /// <param name="organizationSys">The Organization ID for which all doors should be retreived.</param>
    /// <returns></returns>
    [Route("{organizationSys:int}")]
    public IHttpActionResult Get(int organizationSys)
    {
        try
        {
            Dictionary<string, object> parameters = new Dictionary<string, object>();
            parameters.Add("@OrganizationSys", organizationSys);
            List<Door> doors = Repository<Doors>.GetList("WHERE OrganizationSys = @OrganizationSys", parameters).ToList();
            if (doors == null || doors.Count() == 0)
                return Content(HttpStatusCode.NotFound, RejectionMessage.NoItemsFound);

            return Ok(doors);
        }
        catch (Exception ex)
        {
            return Content(HttpStatusCode.BadRequest, ex.Message);
        }
    }

このエンドポイントに対してユニットテストを設定しましたが、完全に機能します。ただし、質問が1つあります。

Swaggerでは、返されるデータオブジェクトの例を示します。メソッドの唯一の戻り値の型はIHttpActionResultであるため、Swaggerでデータモデルが表示されていないことは驚くことではありません。したがって、戻り値のオブジェクト（この場合はList<Door>）より見やすくなりますか？

Swashbuckleはこれをサポートしていますか？

ありがとう！

c#.netapiswaggerswashbuckle
9
Casey Crookston

それはかなり簡単です：

_[Route("{organizationSys:int}")]
[ProducesResponseType(typeof(List<Door>), 200)]
[ProducesResponseType(typeof(string), 400)]
public IHttpActionResult Get(int organizationSys)
_

2つの終了ポイントがあることに注意してください：データを含む通常のリターンとエラーメッセージを返すキャッチは、上記の例で2つの可能な結果タイプを定義しました。

  • http：200（OK）と_List<Door>_
  • http：400（BadRequest）とstring

Swashbuckle Swaggerインフラストラクチャはそれを読み取り、これらのケースのデータの非常に大まかな例を提供します。

ただし、より詳細な例が必要な場合（つまり、合理的なフィールド値を使用する場合）、「サンプルプロバイダ」を実装する必要があります。 詳細とクイックチュートリアルについてはこちらを参照 、要するに：

_[SwaggerRequestExample(typeof(DeliveryOptionsSearchModel), typeof(DeliveryOptionsSearchModelExample))]
public async Task<IHttpActionResult> DeliveryOptionsForAddress(DeliveryOptionsSearchModel search)
_

そして

_public class DeliveryOptionsSearchModelExample : IExamplesProvider
{
  public object GetExamples()
  {
    return new DeliveryOptionsSearchModel
    {
        Lang = "en-GB",
        Currency = "GBP",
        Address = new AddressModel
        {
            Address1 = "1 Gwalior Road",
            Locality = "London",
            Country = "GB",
            PostalCode = "SW15 1NP"
        },
        Items = new[]
        {
            new ItemModel
            {
                ItemId = "ABCD",
                ItemType = ItemType.Product,
                Price = 20,
                Quantity = 1,
                RestrictedCountries = new[] { "US" }
            }
        }
    };
}
_

サンプルプロバイダーは非常に簡単な方法で動作します。プロバイダーが返すものは何でもJSONにシリアル化され、与えられたデータ型の例として返されます。そのように。

これで、メソッドがDeliveryOptionsSearchModelを返した場合、プロバイダーは上記のデータを直接使用します。

または、メソッドがDeliveryOptionsSearchModelと他のいくつかで構成されるより大きなオブジェクトを返した場合、Swaggerは応答プロバイダーの一部にこのプロバイダーを使用し、他のすべての部分に他のプロバイダー（またはデフォルトの大まかな例）を使用しますラージオブジェクト。

上記のすべては、Net Core用でした。

「通常の」Net 4.5/4.6/4.7を使用する場合、Attributeクラスが存在しないため、これらの方法は使用できません。 AspMvc for Net 4.xには、単一の戻り値の型を定義できる[ResponseType(typeof(..))]属性のみがあります。ほとんどの場合、これで問題ありません。ただし、応答コードで戻り値の型を本当に区別する必要がある場合、または適切な例を提供する必要がある場合、それは問題です。

しかしながら！一部の善良な人々はすでにそれを解決しました。 この記事 を参照してください。 NuGet _Swagger.Examples_について説明します。これは非コア向けであり、より良い結果の説明を提供することを目的としています。

別の属性-_[SwaggerResponse(HttpStatusCode.OK, Type=typeof(IEnumerable..._を定義して、可能な結果コードと結果タイプを定義し、Swaggerがその属性を使用するためのプラグインを提供します。

また、別の属性_[SwaggerResponseExample..._を提供します。これは、結果サンプルプロバイダーを定義することを可能にします。きちんとした！

15
quetzalcoatl