6 min read

ASP.NET Core 팁 & 트릭 - swagger 통합

Justin Yoo •

이 포스트는 ASP.NET Core 프레임워크로 애플리케이션을 개발할 때 유용하게 쓸 수 있는 몇가지 팁과 트릭들을 소개하는 포스트들 중 세번째입니다.

API 개발을 하다보면 다른 애플리케이션에서 쉽게 참조를 할 수 있게끔 만들어야 한다. 예전 포스트: Swagger 및 HAL, AutoRest를 이용한 Web API 서비스 콘트랙트 자동화에서도 언급했더랬는데, API 엔드포인트는 개발자 혹은 기계들에게 좀 더 쉬운 접근성 및 가독성을 제공해야 한다는 것이 포인트이다. 이러한 것을 가능하게 하는 것들이 여러가지가 있지만 그들 중 하나가 Swagger이다. Swagger는 Azure 서비스 내부적으로는 일종의 de facto 표준처럼 쓰이고 있기도 하기 때문에 Azure 에서 서비스를 하려면 꼭 알아두는 것이 좋다.

관련 샘플 코드는 아래 링크에서 확인할 수 있다.

Web API 2.x 에서 Swagger 설정

이전 버전의 Web API 에서는 Swagger 통합을 아래와 같이 구현한다.

var config = new HttpConfiguration();
config.EnableSwagger(
c =>
{
c.SingleApiVersion("v1", "Swagger UI");
c.IgnoreObsoleteActions();
c.IgnoreObsoleteProperties();
c.IncludeXmlComments(GetXmlCommentsPath());
c.DescribeAllEnumsAsStrings();
c.UseFullTypeNameInSchemaIds();
})
.EnableSwaggerUi(
c =>
{
c.DocExpansion(DocExpansion.List);
});
view raw web-api-2-swagger-config.cs hosted with ❤ by GitHub

설정에 대한 간략한 설명은 아래와 같다.

  • SingleApiVersion(): API 버전 및 타이틀 설정
  • IgnoreObsoleteActions(): Obsolete 엔드포인트는 포함시키지 않음
  • IgnoreObsoleteProperties(): Obsolete 속성은 포함시키지 않음
  • IncludeXmlComments(): 소스코드에 있는 XML 코멘트들을 엔드포인트 문서화를 위해 포함시킴
  • DescribeAllEnumsAsStrings: enum 값들을 정수형 대신 문자열로 변환시킴
  • UseFullTypeNameInSchemaIds(): Swagger.json 스키마 파일에 클라스 타입 이름을 Short name 대신 Full name으로 작성함
  • DocExpansion(DocExpansion.List): Swagger UI 화면에서 API 엔드포인트를 리스트 형태로 보여줌

ASP.NET Core 에서 Swagger 설정

지난 포스트와 마찬가지로 HttpConfiguration 클라스는 더이상 존재하지 않고 대신 미들웨어 형태로 Swagger 서비스가 주입되므로, 위와 동일한 설정을 위해서는 ConfigureServices() 메소드를 수정해야 한다. 우선 최신 버전의 Swashbuckle 라이브러리를 NuGet으로부터 다운로드 받는다. 이 글을 쓰는 현재 ASP.NET Core에서 사용할 수 있는 Swashbuckle의 최신 버전은 6.0.0-rc1-final이다.

NuGet 패키지를 인스톨하고 나면 Startup.cs 파일의 ConfigureServices() 메소드를 아래와 같이 수정한다.

public IServiceProvider ConfigureServices(IServiceCollection services)
{
...
services.AddSwaggerGen();
services.ConfigureSwaggerDocument(
options =>
{
options.SingleApiVersion(new Info() { Version = "v1", Title = "Swagger UI" });
options.IgnoreObsoleteActions = true;
options.OperationFilter(new ApplyXmlActionComments(GetXmlPath(appEnv)));
});
services.ConfigureSwaggerSchema(
options =>
{
options.DescribeAllEnumsAsStrings = true;
options.IgnoreObsoleteProperties = true;
options.CustomSchemaIds(type => type.FriendlyId(true));
options.ModelFilter(new ApplyXmlTypeComments(GetXmlPath(appEnv)));
});
...
}
private static string GetXmlPath(IApplicationEnvironment appEnv)
{
var assembly = typeof(Startup).GetTypeInfo().Assembly;
var assemblyName = assembly.GetName().Name;
var path = $@"{appEnv.ApplicationBasePath}\{assemblyName}.xml";
if (File.Exists(path))
{
return path;
}
var config = appEnv.Configuration;
var runtime = $"{appEnv.RuntimeFramework.Identifier.ToLower()}{appEnv.RuntimeFramework.Version.ToString().Replace(".", string.Empty)}";
path = $@"{appEnv.ApplicationBasePath}\..\..\artifacts\bin\{assemblyName}\{config}\{runtime}\{assemblyName}.xml";
return path;
}
view raw configure-services-swagger.cs hosted with ❤ by GitHub

또한 Configure() 메소드를 통해 Swagger를 사용할 수 있게끔 미들웨어를 등록해 주어야 한다.

public void Configure(IApplicationBuilder app)
{
...
app.UseSwaggerGen();
app.UseSwaggerUi();
...
}
view raw configure-swagger.cs hosted with ❤ by GitHub

몇가지 눈여겨 봐두어야 할 포인트가 있다.

  • Configure() 메소드 안에 UseSwaggerGen() 미들웨어와 UseSwaggerUi() 미들웨어를 별도로 등록한다. 이는 향후 swagger.json 스키마 생성과 Swagger UI 문서 생성을 따로 가져가겠다는 의미로 보인다.
  • 이와 더불어 ConfigureServices() 메소드에서는 스키마 생성과 관련한 옵션과 UI 관련 옵션을 따로 설정할 수 있다. 이전 버전에 가능했던 UI의 자바스크립트 또는 CSS 설정을 커스터마이징할 수 있는 부분은 아직 API가 오픈되지 않았지만 곧 정식 버전이 나오면 가능해질 것으로 예상한다.

이렇게 설정이 끝나고 나면 친숙한 Swagger UI 페이지를 아래와 같이 확인할 수 있다.

지금까지 ASP.NET Core 애플리케이션에서 Swagger 도큐먼트를 설정하는 방법에 대해 간략하게 논의해 보았다. 다음 포스트에서는 에러 핸들링을 위한 ExceptionFilter 설정에 대해 논의해 보도록 한다.