Web API 規約を使用する

[アーティクル]
11/30/2023

一般的な API 文書を抽出し、複数のアクション、コントローラー、またはアセンブリ内のすべてのコントローラーに適用することができます。 Web API 規約は、[ProducesResponseType] による個々のアクションの装飾の代わりになるものです。

規約を使用すると、次のことを実行できます。

特定の型のアクションから返される最も一般的な戻り値の型と状態コードを定義する
定義済みの標準から外れるアクションを識別する

既定の規約は Microsoft.AspNetCore.Mvc.DefaultApiConventions から利用できます。この規約は、API プロジェクトテンプレートに追加された ValuesController.cs で示されています。

using Microsoft.AspNetCore.Mvc;
using System.Collections.Generic;

namespace WebApp1.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class ValuesController : ControllerBase
    {
        // GET api/values
        [HttpGet]
        public ActionResult<IEnumerable<string>> Get()
        {
            return new string[] { "value1", "value2" };
        }

        // GET api/values/5
        [HttpGet("{id}")]
        public ActionResult<string> Get(int id)
        {
            return "value";
        }

        // POST api/values
        [HttpPost]
        public void Post([FromBody] string value)
        {
        }

        // PUT api/values/5
        [HttpPut("{id}")]
        public void Put(int id, [FromBody] string value)
        {
        }

        // DELETE api/values/5
        [HttpDelete("{id}")]
        public void Delete(int id)
        {
        }
    }
}

ValuesController.cs のパターンに従うアクションは、既定の規則を使用して動作します。既定の規約がニーズに合わない場合は、「Web API 規約を作成する」を参照してください。

実行時に、Microsoft.AspNetCore.Mvc.ApiExplorer は規約を理解します。 ApiExplorer は OpenAPI (Swagger とも呼ばれている) ドキュメントのジェネレーターと通信するために MVC を抽象化したものです。適用された規約の属性はアクションと関連付けられており、アクションの OpenAPI ドキュメントに含まれます。 API アナライザーでも、規約を理解します。従来とは異なるアクションである場合 (適用されている規約で文書化されていない状態コードを返す場合など)、警告で状態コードの文書化が促されます。

サンプルコードを表示またはダウンロードします (ダウンロード方法)。

Web API 規約を適用する

規約では作成は行われません。各アクションを 1 つの規約だけに関連付けることができます。より具体的な規約の方が一般的な規約より優先されます。優先順位が同じである 2 つ以上の規約が 1 つのアクションに適用されていると、選択は不明確になります。次のオプションは、規約をアクションに適用するためにあります。より具体的なものから並んでいます。

Microsoft.AspNetCore.Mvc.ApiConventionMethodAttribute — 個々のアクションに適用され、適用される規約の種類と規約のメソッドが指定されます。

次の例では、既定の規約の種類の Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put 規約のメソッドが、Update アクションに適用されます。

// PUT api/contactsconvention/{guid}
[HttpPut("{id}")]
[ApiConventionMethod(typeof(DefaultApiConventions), 
                     nameof(DefaultApiConventions.Put))]
public IActionResult Update(string id, Contact contact)
{
    var contactToUpdate = _contacts.Get(id);

    if (contactToUpdate == null)
    {
        return NotFound();
    }

    _contacts.Update(contact);

    return NoContent();
}

Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put 規約のメソッドでは、次の属性がアクションに適用されます。

[ProducesDefaultResponseType]
[ProducesResponseType(StatusCodes.Status204NoContent)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]

[ProducesDefaultResponseType] の詳細については、既定の応答に関する記事をご覧ください。

Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute (コントローラーに適用) — 指定した規約の種類がコントローラー上のすべてのアクションに適用されます。規約のメソッドは、規約のメソッドが適用されるアクションを決定するヒントでマークされています。ヒントの詳細については、「Web API 規約を作成する」を参照してください。

次の例では、一連の既定の規約が、ContactsConventionController のすべてのアクションに適用されます。
```
[ApiController]
[ApiConventionType(typeof(DefaultApiConventions))]
[Route("api/[controller]")]
public class ContactsConventionController : ControllerBase
{
```
Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute (アセンブリに適用) — 指定した規約の種類が、現在のアセンブリ内のすべてのコントローラーに適用されます。 Startup.cs ファイル内でアセンブリレベルの属性を適用することをお勧めします。

次の例では、一連の既定の規約が、アセンブリのすべてのコントローラーに適用されます。
```
[assembly: ApiConventionType(typeof(DefaultApiConventions))]
namespace ApiConventions
{
    public class Startup
    {
```

Web API 規約を作成する

既定の API 規約がニーズに合わない場合は、独自の規約を作成します。規約は次のようなものです。

メソッドを含む静的な種類
アクションで応答の種類と名前付けの要件を定義できる

応答の種類

これらのメソッドには [ProducesResponseType] または [ProducesDefaultResponseType] 属性の注釈が付けられています。次に例を示します。

public static class MyAppConventions
{
    [ProducesResponseType(StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status404NotFound)]
    public static void Find(int id)
    {
    }
}

より詳細なメタデータ属性が存在しない場合、この規約がアセンブリに適用されると次のことが適用されます。

規約のメソッドは、Find という名前のアクションに適用されます。
id という名前のパラメーターは、Find アクションに存在します。

名前付けの要件

[ApiConventionNameMatch] 属性と [ApiConventionTypeMatch] 属性は、適用されるアクションを決定する規約のメソッドに適用することができます。次に例を示します。

[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
[ApiConventionNameMatch(ApiConventionNameMatchBehavior.Prefix)]
public static void Find(
    [ApiConventionNameMatch(ApiConventionNameMatchBehavior.Suffix)]
    int id)
{ }

前の例の場合:

メソッドに適用された Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Prefix オプションは、規約が "Find" というプレフィックスがあるアクションに一致することを示します。 Find、FindPet、および FindById を含む照合アクションの例。
パラメーターに適用された Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Suffix は、規約がサフィックス識別子で終わる 1 つのパラメーターが含まれるメソッドと一致することを示します。例には、id や petId などのパラメーターが含まれます。 ApiConventionTypeMatch も同様に型に適用して、パラメーターの型に制約を設けることができます。 params[] の引数では、明示的に一致する必要がない残りのパラメーターを示します。