웹 API 분석기 사용

  • 아티클

ASP.NET Core 2.2에서는 웹 API 프로젝트와 함께 사용하기 위한 MVC 분석기 패키지를 제공합니다. 분석기는 ApiControllerAttribute로 주석을 단 컨트롤러와 함께 작동하지만 웹 API 규칙으로 빌드됩니다.

분석기 패키지는 다음을 수행하는 컨트롤러 작업을 모두 알려줍니다.

  • 선언되지 않은 상태 코드를 반환
  • 선언되지 않은 성공 결과를 반환
  • 반환되지 않은 상태 코드를 문서화
  • 명시적 모델 유효성 검사를 포함

분석기 패키지 참조

분석기는 .NET Core SDK에 포함되어 있습니다. 프로젝트에서 분석기를 사용하도록 설정하려면 프로젝트 파일에 IncludeOpenAPIAnalyzers 속성을 포함합니다.

<PropertyGroup>
 <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers>
</PropertyGroup>

웹 API 규칙용 분석기

OpenAPI 문서에는 작업이 반환할 수 있는 상태 코드 및 응답 형식이 포함되어 있습니다. ASP.NET Core MVC에서는 ProducesResponseTypeAttribute 및 ProducesAttribute 와 같은 특성을 사용하여 작업을 문서화합니다. Swagger/OpenAPI를 사용하는 ASP.NET Core 웹 API 문서는 웹 API를 문서화하는 데 대해 자세히 설명합니다.

패키지의 분석기 중 하나는 ApiControllerAttribute로 주석을 단 컨트롤러를 검사하고 응답을 완전히 문서화하지 않은 작업을 식별합니다. 다음 예제를 참조하세요.

// GET api/contacts/{guid}
[HttpGet("{id}", Name = "GetById")]
[ProducesResponseType(typeof(Contact), StatusCodes.Status200OK)]
public IActionResult Get(string id)
{
    var contact = _contacts.Get(id);

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

    return Ok(contact);
}

앞의 작업은 HTTP 200 성공 반환 유형을 문서화하지만 HTTP 404 실패 상태 코드는 문서화하지 않습니다. 분석기는 HTTP 404 상태 코드에 대한 누락된 설명서를 경고로 보고합니다. 문제를 해결하기 위한 옵션이 제공됩니다.

analyzer reporting a warning

분석기에서 Microsoft.NET.Sdk.Web 필요

분석기는 Sdk="Microsoft.NET.Sdk"를 참조하는 라이브러리 프로젝트에서 작동하지 않습니다.

추가 리소스