Swagger 및 ASP.NET Web API - 1 부 : Web API 프로젝트에 Swagger 추가

원문 : http://wmpratt.com/swagger-and-asp-net-web-api-part-1/

Swagger 및 ASP.NET Web API - 1 부 : Web API 프로젝트에 Swagger 추가

이것은 ASP.NET Web API 에서 Swagger를 사용하는 시리즈 중 하나입니다.

이 시리즈의 모든 소스 코드는 여기 에서 찾을 수 있습니다 .

ASP.NET Web API 프로젝트를 만들면  Microsoft ASP.NET Web Api Help Page 가 설치되어 사이트의 Web API 에 대한 도움말 페이지 콘텐츠를 생성합니다.  help page 패키지는 좋은 기능이지만,   discoverability (발견 가능성) 및 실제 상호 작용과 같은 요소가 다소 부족합니다. 하지만 Swagger 로 하면 이는 가능합니다.

"Swagger는 RESTful API의 단순하지만 강력한 표현입니다. 수천 명의 개발자가 거의 모든 최신 프로그래밍 언어 및 배포 환경에서 Swagger를 지원하고 있습니다. Swagger 지원 API를 사용하면 interactive 설명서, 클라이언트 SDK 생성 및 검색 기능을 사용할 수 있습니다. "

- swagger.io

ASP.NET Web API Help Page 설명서

Swagger 문서

Swagger를 웹 API에 추가 할 경우, ASP.NET Web API help pages 도 함께 사용할 수 있습니다. 원한다면 두 가지를 모두 나란히 실행할 수 있습니다.

Web Api 프로젝트에 Swagger 추가하기

Swagger를 ASP.NET 웹 API에 추가하기 위해 Nuget을 통해 Swashbuckle 이라는 오픈 소스 프로젝트를 설치합니다 .

패키지를 설치 한 후 솔루션 탐색기에서 App_Start로 이동하십시오. SwaggerConfig.cs라는 새 파일이 생성되어 있는 것을 볼 수 있습니다. 이 파일은 Swagger가 활성화 된 곳이며, 여기에 모든 환경 옵션을 설정합니다.

Swagger 구성

최소한 Swagger 및 Swagger UI를 사용하려면이 아래 구문이 필요합니다.

GlobalConfiguration.Configuration
  .EnableSwagger(c => c.SingleApiVersion("v1", "A title for your API"))
  .EnableSwaggerUi();

디버깅  (F5)을 시작하고 http://localhost : [PORT_NUM] / swagger로 이동합니다. 접속 하면 아래와 같이 API에 대한 Swagger UI 도움말 페이지가 표시됩니다.

API를 확장하고 "Try it out!"버튼을 클릭하면 해당 API를 호출하고 결과를 반환합니다. 정말 멋지죠?

XML 주석을 사용하려면 Swagger 활성화 하기

최소한의 환경구성으로 시작하는 것도 좋지만, 더 많은 사용자 정의를 추가해 보겠습니다. XML 주석을 사용하여 Swagger 메타 데이터에 세부 정보를 추가하도록 Swashbuckle에 알릴 수도 있습니다. 
이들은 ASP.NET 도움말 페이지에서 사용하는 것과 동일한 XML 주석입니다.

먼저, 빌드하는 동안 XML 문서 파일 작성을 사용 가능하게 합니다. 솔루션 탐색기는 웹 API 프로젝트를 마우스 오른쪽 단추로 클릭하고 속성 중에  Build 탭을 클릭하고 output으로 이동하십시오 . XML 문서 파일이 체크되어 있는지 확인하시고, default file path를 그대로 둘 수도 있습니다. 아래 경우는 bin \ SwaggerDemoApi.XML 로 설정했습니다.

다음으로 Swagger 메타 데이터에 XML 주석을 포함하도록 Swashbuckle에 알릴 필요가 있습니다. SwaggerConfig.cs에 다음 행을 추가하십시오. 파일 경로를 XML 문서 파일의 경로로 변경하십시오.

c.IncludeXmlComments(string.Format(@"{0}\bin\SwaggerDemoApi.XML", System.AppDomain.CurrentDomain.BaseDirectory));

지금까지 기술한 것을 정리하자면...

GlobalConfiguration.Configuration
  .EnableSwagger(c =>
    {
      c.SingleApiVersion("v1", "SwaggerDemoApi");
      c.IncludeXmlComments(string.Format(@"{0}\bin\SwaggerDemoApi.XML",           
                           System.AppDomain.CurrentDomain.BaseDirectory));
    })
  .EnableSwaggerUi();

마지막으로, 아직 작성하지 않았다면 Models 및 API 메소드에 XML 주석을 추가하세요.

프로젝트를 실행하고 /swagger로 돌아갑니다. API 문서에 추가 된 세부 정보가 표시되어 있는지 확인해 보세요.. 
필자는 해당 XML 주석으로 아래에 몇 가지를 강조했습니다. 

Response Class 아래에 있는  , Model 를 클릭하세요. 그러면  모델에 XML comments 가 추가 된 것을 볼 수 있습니다.

Enum을 문자열로 설명하기

Superhero 클래스에는 Universe 라는 Enum 속성이 포함되어 있습니다.이 속성은 해당 Universe 에 속한 comic universe 를 나타냅니다.

기본적으로 Swagger는 이러한 Enum 값을 정수 값으로 표시합니다. 하지만 여기서는 문자열로 표시하도록 변경합시다.

SwaggerConfig.cs에 다음 구문을 추가합니다.

c.DescribeAllEnumsAsStrings();

그 동안 기술한 부분을 다시 정리하면...

GlobalConfiguration.Configuration
  .EnableSwagger(c =>
  {
    c.SingleApiVersion("v1", "SwaggerDemoApi");
    c.IncludeXmlComments(string.Format(@"{0}\bin\SwaggerDemoApi.XML", 
                         System.AppDomain.CurrentDomain.BaseDirectory));
    c.DescribeAllEnumsAsStrings();
  })
  .EnableSwaggerUi();

지금 Swagger를 보면 유니버스 enum type 값이 문자열로 표시됩니다. 가독성이 훨씬 좋네요!

Swagger에서 Swagger 메타 데이터를 만들 때 지정할 수있는 여러 가지 구성 옵션 중 일부입니다. Swashbuckle의 GitHub 에있는 다른 옵션을 살펴 보시기 바랍니다 .

Swagger JSON 파일

지금까지 API Swagger 메타 데이터를 UI로 표현했습니다. 실제 "Swagger"를 보려면 Swagger UI 문서 페이지의 헤더에 있는 URL로 이동하십시오. 

이것이 API를 검색 할 수있는 방법(discoverable)입니다. Swagger 메타 데이터는 다른 API에 상호 작용 방법을 알려주는 데 사용할 수 있습니다. customers/users/integration partners 에게 배포 할 수 있는 API와 상호 작용할 수있는 클라이언트 라이브러리를 만들 수도 있습니다.

다음은 내 Swagger 메타 데이터 샘플입니다.

Microsoft Azure 팀은 현재 현재 미리보기에서 새로운 Azure App 서비스에 Swagger를 포함시키고 있습니다. Scott Hanselman 과 Scott Hunter 와 함께 Azure App Service Architecture 에 관한 // build / 2015 이야기를 보는 것이 좋습니다 .

이 시리즈의 소스 코드 : github.com/billpratt/SwaggerDemoApi

관련 게시물

• 파트 II : OAuth 2.0 사용