OpenAPI 설명서에 XML 주석 추가
Swagger UI를 사용하면 원본 코드에 액세스하지 않고도 API의 리소스와 상호 작용하고 이를 시각화할 수 있습니다. OpenAPI 사양에서 API의 그래픽 표현이 자동으로 생성되며, 다른 개발자가 해당 API를 사용하는 앱을 더욱 쉽게 빌드할 수 있도록 도와줍니다.
Swagger UI는 다음 이미지에서 볼 수 있듯이 작업과 메서드를 명확하게 시각화해 줍니다.
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에서 볼 수 있습니다.
데이터 주석
데이터 주석도 마찬가지입니다. 모델에 주석을 추가하기만 하면 Swagger가 API 문서에 이를 포함시킵니다.
예를 들어, 다음과 같은 주석을 컨트롤러에 포함시키는 경우를 살펴보겠습니다.
[Produces("application/json")]
... 추가된 정보가 Swagger UI에 표시됩니다.
팁
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")]