[ASP.NET Core Web API] Swagger와 API 명세

백엔드에서 API를 만들고 나면 프런트엔드에서 이를 활용하기 위해 어떤 방법으로 필요한 데이터를 전송하고 받을지에 대한 설명서가 필요합니다. 이를 API명세라고도 하며 Swagger를 사용하면 API명세가 담긴 UI를 손쉽게 생성할 수 있고 테스트도 가능합니다.

 

Swagger를 사용하기 위해서는 우선 NuGet Package에서 'Swashbuckle.AspNetCore'를 검색해 해당 Package를 설치해 줍니다.

 

그리고 startup.cs에서 ConfigureServices() 메서드에서 다음과 같이 API 문서의 제목과 버전 정보 등을 등록합니다.

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "myapi", Version = "v1" });
});

이후 Configure() 메서드에서 Swagger를 사용하기 위한 설정을 추가합니다. 위에서 버전 정보를 v1이라고 하였으므로 swagger 설정에도 /swagger/v1/swagger.json에서 v1처럼 동알 하게 맞춰줍니다.

app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "json menual");
});

이것으로 모든 설정이 완료되었습니다. 이제 만들어진 프로젝트에서 /swagger 주소로 들어가게 되면 전체 컨트롤러의 모든 API 메서드를 뒤져서 그에 맞는 사양들을 화면에 표시하게 됩니다.

 

그런데 순조롭게 되지 않고 오류가 발생할 수도 있습니다. 오류의 대부분은 API에서 드에서 [httpGet]가 같은 어트리뷰트 등을 설정하지 않아서 생기는 문제입니다. 특정 메서드는 API와 관련이 없을 수도 있는데 그런 메서드에 대해서는 [NonAction]과 같은 메서드를 붙여줘야 합니다.

 

만약 오류가 발생한다면 위에서 Swagger사용을 등록할 때의 json주소인 '/swagger/v1/swagger.json'으로 들어가면 정확히 어떤 부분에서 오류가 발생하는지를 알 수 있습니다.

 

따라서 오류가 발생하면 위와 같은 설명을 참고하여 문제점을 찾아 수정해 주면 됩니다.

 

참고로 API마다 특정 그룹으로 분리하려면 API메서드에서 ApiExplorerSettings 어트리뷰트를 통해 group을 지정할 수 있으며

[ApiExplorerSettings[GroupName = "myGroup")]

경우에 따라 어떤 메서드는 표시하지 않기를 원할 수도 있는데 그런 메서드는 아래와 같이 설정해 줄 수 있습니다.

[ApiExplorerSettings(IgnoreApi=true)]

기본 적으로 표시해주는 UI만으로 API명세를 확인하는데 충분하지만 간혹 별도의 설명이 필요한 경우가 있습니다. 그런 경우는 XML을 통해 도움말 표시를 추가할 수 있습니다.

 

프로젝트에서 마우스오른쪽 버튼을 눌러 csproj 편집(Edit Project File)을 선택하면 <프로젝트>.csproj 파일이 열리게 되는데 아래 2줄을 PropertyGroup에 추가해 줍니다.

<GenerateDocumentationFile>true</GenerateDocumentationFile> <NoWarn>$(NoWarn);1591</NoWarn>

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
    <DocumentationFile></DocumentationFile>
	<GenerateDocumentationFile>true</GenerateDocumentationFile>
	<NoWarn>$(NoWarn);1591</NoWarn>
  </PropertyGroup>

참고로 GenerateDocumentationFile 부분을 활성화 하면 프로젝트의 소스코드에서 모든 클래스나 메서드에 대해 경고를 표시하게 되는데 이를 방지하기 위해 NoWarn부분도 같이 추가해야 합니다.

 

그리고 startup.cs의 ConfigureServices() 메서드 중 위에서 정의한 services.AddSwaggerGen 아래에 XML처리와 관련된 내용을 추가합니다.

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "api", Version = "v1" });

    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
});

그런다음 설명이 필요한 Action Method에 다음과 같은 방법으로 설명을 추가합니다.

/// <summary>
/// 시스템관리 -> 프로그램등록에서 시스템을 등록합니다.
/// </summary>
/// <param name="system"></param>
/// <returns></returns>
[HttpPost]
[Route("[Action]")]
[Authorize(RequestType.Save)]
public IActionResult SetSystem([FromBody] AccSystem system)

그럼 Swagger UI 페이지에서 다음과 같이 설명이 표시됩니다.