Web API 분석기 사용

ASP.NET Core는 웹 API 프로젝트에 사용하기 위한 MVC 분석기 패키지를 제공합니다. 분석기는 ApiControllerAttribute을 기반으로 구축된 주석이 추가된 컨트롤러에서 작동합니다.

분석기 패키지는 다음과 같은 특정 컨트롤러 작업에 대해 알림을 제공합니다.

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

분석기 패키지 참조

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

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

웹 API 규칙에 대한 분석기

OpenAPI 문서에는 작업에서 반환할 수 있는 상태 코드 및 응답 형식이 포함되어 있습니다. ASP.NET Core MVC에서는 작업을 문서화하는 데 사용되는 특성과 ProducesResponseTypeAttribute 같은 ProducesAttribute 특성이 있습니다. Swagger/OpenAPI를 사용한 ASP.NET Core Web 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 상태 코드에 대한 누락된 설명서를 경고로 보고합니다. 문제를 해결하는 옵션이 제공됩니다.

분석기에는 Microsoft.NET.Sdk.Web이 필요합니다.

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

추가 리소스

• 웹 API 규칙 사용
• Swagger/OpenAPI를 사용하는 ASP.NET Core Web API 설명서
• ASP.NET Core로 웹 API 만들기