OpenAPI 설명서에 XML 주석 추가

  • 4분

Swagger UI를 사용하면 원본 코드에 액세스하지 않고도 API의 리소스와 상호 작용하고 이를 시각화할 수 있습니다. OpenAPI 사양에서 API의 그래픽 표현이 자동으로 생성되며, 다른 개발자가 해당 API를 사용하는 앱을 더욱 쉽게 빌드할 수 있도록 도와줍니다.

Swagger UI는 다음 이미지에서 볼 수 있듯이 작업과 메서드를 명확하게 시각화해 줍니다.

Operations of API in Swagger UI.

Swagger UI를 사용하면 각 작업과 상호 작용하고 이를 직접 사용해 볼 수도 있습니다.

Interaction with API Operation in Swagger UI.

Swashbuckle 및 Swagger 도구를 사용하여 API 설명서를 자동으로 생성하면 제3자가 API의 리소스를 파악하는 데 도움이 됩니다. 그렇다면 한 걸음 더 나아가 보다 상세한 정보를 제공하려는 경우에는 어떻게 해야 할까요? API를 처음 사용할 때는 가능한 한 많은 정보를 살펴봐야 합니다.

XML 주석

XML 주석을 포함하여 코드의 문서를 생성할 수 있습니다. 이러한 주석은 보통 해당 주석이 설명하는 코드 블록 바로 앞에 배치하게 됩니다.

/// <summary>
/// Returns a group of Employees matching the given first and last names.
/// </summary>
/// <remarks>
/// Here is a sample remarks placeholder.
/// </remarks>
/// <param name="firstName">The first name to search for</param>
/// <param name="lastName">The last name to search for</param>
/// <returns>A string status</returns>
[HttpGet]
[Route("byname/{firstName}/{lastName}")]
public ActionResult<string> GetByName(string firstName, string lastName)
{
    return "Found another University employee";
}

여기서 사용되는 XML 노드는 다음과 같습니다.

  • 요약: 메서드/클래스/필드의 역할과 기능에 대한 개략적인 요약입니다.
  • 설명: 메서드/클래스/필드에 대한 추가 설명입니다.
  • 매개 변수: 메서드에 입력되는 매개 변수와 각각의 의미입니다.
  • 반환: 메서드가 반환하는 것에 대한 설명입니다.

XML 주석을 사용하도록 설정하면 Swashbuckle 도구는 OpenAPI 설명서에 XML 설명서 주석을 포함할 수 있으며 Swagger UI에서 볼 수 있습니다.

Image showing Swagger UI and added XML Comments.

데이터 주석

데이터 주석도 마찬가지입니다. 모델에 주석을 추가하기만 하면 Swagger가 API 문서에 이를 포함시킵니다.

예를 들어, 다음과 같은 주석을 컨트롤러에 포함시키는 경우를 살펴보겠습니다.

[Produces("application/json")]

... 추가된 정보가 Swagger UI에 표시됩니다.

Image showing Swagger UI with added content type added to annotations.

팁

API를 설명할 때 사용해야 하는 여러 데이터 주석이 있습니다.

  • API가 요청 및 응답에서 처리하는 content-types를 식별합니다. 다음 특성은 API가 양방향으로 application/json 콘텐츠 형식만 사용하도록 지정합니다.

    [Produces("application/json")]
[Consumes("application/json")]

  • 호출하는 클라이언트에 반환될 수 있는 잠재적인 HTTP 응답 코드를 식별합니다. 다음 특성은 404 찾을 수 없음을 반환할 수 있는 API를 보여 줍니다.

    [ProducesResponseType(StatusCodes.Status404NotFound)]

    API는 표준 응답 코드 세트를 생성할 수 있으며, 이 경우 각각 개별적으로 지정하는 대신 다음 특성을 사용하여 200, 400 및 404를 지정할 수 있습니다. 웹 API 규칙 사용에 대해 자세히 알아보세요.

    [ApiConventionMethod(typeof(DefaultApiConventions))]

  • operationId를 생성하여 설명서, 코드 생성, 다른 서비스와의 통합을 비롯한 API 사용 환경을 크게 향상할 수 있습니다. HTTP 동사 필터에 Name 속성을 포함하여 operationId를 자동으로 생성할 수 있습니다.

    [HttpGet("{Height}/{Width}", Name="GetPrice")]