웹 API 규칙 사용

  • 아티클

일반적인 API 문서를 추출하여 어셈블리 내의 여러 작업, 컨트롤러 또는 모든 컨트롤러에 적용할 수 있습니다. 웹 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 따르는 작업입니다. 기본 규칙이 요구 사항을 충족하지 못하는 경우 웹 API 규칙 만들기를 참조하세요.

런타임 시 Microsoft.AspNetCore.Mvc.ApiExplorer가 규칙을 이해합니다. ApiExplorer는 OpenAPI(Swagger라고도 함) 문서 생성기와 통신하기 위한 MVC의 추상화입니다. 적용된 규칙의 특성은 작업과 연결되며 작업의 OpenAPI 설명서에 포함됩니다. API 분석기도 규칙을 이해합니다. 작업이 색다른 경우(예를 들어 적용된 규칙에 의해 문서화되지 않은 상태 코드를 반환하는 경우) 경고는 상태 코드를 문서화할 것을 권장합니다.

샘플 코드 보기 및 다운로드(다운로드 방법)

웹 API 규칙 적용

규칙이 구성되지 않으면 각 작업은 정확히 하나의 규칙과 연결될 수 있습니다. 더 구체적인 규칙은 덜 구체적인 규칙보다 우선합니다. 동일한 우선순위의 둘 이상의 규칙이 작업에 적용되는 경우 선택은 명확하지 않습니다. 다음 옵션은 가장 구체적인 것에서 가장 덜 구체적인 것까지 작업에 규칙을 적용할 수 있습니다.

  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]에 대한 자세한 내용은 Default Response(기본 응답)를 참조하세요.

  2. 컨트롤러에 Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute를 적용하면 컨트롤러에서 모든 작업에 지정된 규칙 유형을 적용합니다. 규칙 메서드는 규칙 메서드가 적용되는 작업을 결정하는 힌트로 표시됩니다. 힌트에 대한 자세한 내용은 웹 API 규칙 만들기를 참조하세요).

    다음 예제에서는 ContactsConventionController의 모든 작업에 기본 규칙 집합이 적용됩니다.

    [ApiController]
[ApiConventionType(typeof(DefaultApiConventions))]
[Route("api/[controller]")]
public class ContactsConventionController : ControllerBase
{

  3. 어셈블리에 적용된 Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute는 현재 어셈블리의 모든 컨트롤러에 지정된 규칙 유형을 적용합니다. 권장 사항으로 파일에 어셈블리 수준 특성을 적용합니다 Startup.cs .

    다음 예제에서는 기본 규칙 집합이 어셈블리의 모든 컨트롤러에 적용됩니다.

    [assembly: ApiConventionType(typeof(DefaultApiConventions))]
namespace ApiConventions
{
    public class Startup
    {

웹 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, FindPet 및 FindById가 있습니다.
  • 매개 변수에 적용된 Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Suffix는 규칙이 접미사 식별자로 끝나는 정확히 하나의 매개 변수와 메서드가 일치함을 나타냅니다. 예제에는 id 또는 petId와 같은 매개 변수가 포함됩니다. ApiConventionTypeMatch는 매개 변수 유형을 제한하는 형식에 유사하게 적용할 수 있습니다. params[] 인수는 명시적으로 일치할 필요가 없는 나머지 매개 변수를 나타냅니다.

추가 리소스