Web API 規則を使用する

2025-07-30

一般的な API ドキュメントは、アセンブリ内の複数のアクション、コントローラー、またはすべてのコントローラーに抽出して適用できます。 Web API 規則は、個々のアクションを [ProducesResponseType]で修飾する代わりに使用されます。

規則を使用すると、次のことができます。

特定の種類のアクションから返される最も一般的な戻り値の型と状態コードを定義します。
定義された標準から逸脱したアクションを特定します。

既定の規則は、 Microsoft.AspNetCore.Mvc.DefaultApiConventionsから使用できます。規則は、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 つ以上の規則がアクションに適用される場合、選択は非決定論的です。アクションに規則を適用するには、最も具体的なものから最も具体的なものまで、次のオプションがあります。

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 規則がニーズを満たしていない場合は、独自の規則を作成します。規則は次のとおりです。

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

Response types

これらのメソッドには、 [ProducesResponseType] 属性または [ProducesDefaultResponseType] 属性で注釈が付けられます。 For example:

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

より具体的なメタデータ属性がない場合、アセンブリにこの規則を適用すると、次のことが強制されます。

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

Naming requirements

[ApiConventionNameMatch]属性と[ApiConventionTypeMatch]属性は、適用するアクションを決定する規則メソッドに適用できます。 For example:

[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[]引数は、明示的に一致する必要のない残りのパラメーターを示します。

次の方法で共有

Web API 規則を使用する

Web API 規則を適用する

Web API 規則を作成する

Response types

Naming requirements

Additional resources

フィードバック

その他のリソース