다음을 통해 공유

웹 API 규칙 사용

일반적인 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 패턴을 따르는 작업은 기본 규칙과 함께 작동합니다. 기본 규칙이 요구 사항을 충족하지 않는 경우 웹 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]내용은 기본 응답을 참조하세요.

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

추가 리소스

  • Last updated on