Swagger 도구를 사용하여 ASP.NET Core Web API 문서화
API는 무척 유용하지만, 개발자가 사용법을 알아야 제대로 활용할 수 있습니다. 개발자들은 가능한 한 빨리 API를 통합하고 싶어 합니다. 양질의 API 문서는 개발자가 API의 기능과 사용법을 파악하는 데 도움을 주어 더욱 효율적으로 통합할 수 있도록 해 줍니다.
지금까지는 API와 그 사용법을 설명하는 문서가 모두 손으로 작성되었습니다. 이제 OpenAPI라는 API 설명에 대한 표준 사양이 생겼습니다. Swagger UI는 API에 대한 OpenAPI 사양의 구현 및 테스트 도구를 제공합니다. Swashbuckle은 .NET 리플렉션을 사용하여 웹 API 컨트롤러에서 직접 OpenAPI 설명 문서를 자동으로 생성하는 오픈 소스 패키지입니다. Swashbuckle은 설명 프로세스를 자동화하여 팀이 OpenAPI 기반 API 설명서를 쉽게 생성, 유지 관리 및 사용할 수 있도록 도와줍니다. 사용자가 API에 대해 기술하면 도구에서 자동으로 다양한 기능을 갖춘 문서가 생성됩니다.
OpenAPI란?
OpenAPI는 REST API를 기술하는 데 사용되는 사양입니다. OpenAPI는 언어 중립적이며, 다음을 비롯한 API 전체를 기술할 수 있습니다.
- 사용 가능한 엔드포인트
- 조작 매개 변수
- 인증 방법
- 연락처 및 기타 정보
API 사양은 YAML이나 JSON으로 작성할 수 있습니다. OpenAPI 사양을 사용하면 사용자와 컴퓨터가 소스 코드에 액세스하지 않고도 API의 기능을 이해할 수 있습니다.
Swagger란?
Swagger는 OpenAPI 사양을 중심으로 빌드된 오픈 소스 도구 세트입니다. 이러한 도구를 사용하면 REST API를 디자인, 빌드 및 문서화할 수 있습니다. Swagger는 API의 OpenAPI 사양을 사용하여 해당 구조를 이해합니다.
예를 들어, Swagger UI는 OpenAPI 사양으로 정의된 API의 문서를 브라우저에서 시각적으로 렌더링하는 도구입니다. Swagger Codegen은 API의 OpenAPI 사양을 바탕으로 클라이언트 SDK를 생성할 수 있습니다.
Swashbuckle이란?
Swashbuckle은 .NET 리플렉션을 사용하여 .NET Core API용 Swagger 설명서를 생성하는 데 사용되는 오픈 소스 Swagger 구현입니다.
Swashbuckle에는 다음과 같은 세 가지 주요 구성 요소가 있습니다.
Swashbuckle.AspNetCore.Swagger: 이 구성 요소는
SwaggerDocument개체를 JSON 엔드포인트로 노출해 주는 Swagger 개체 모델이자 미들웨어입니다.Swashbuckle.AspNetCore.SwaggerGen: 이 라이브러리는 경로, 컨트롤러 및 모델에서 직접
SwaggerDocument개체를 빌드해 주는 Swagger 생성기입니다. 라이브러리는 일반적으로 Swagger 엔드포인트 미들웨어와 결합되어 Swagger JSON을 자동으로 노출합니다.Swashbuckle.AspNetCore.SwaggerUI: 이 패키지는 Swagger UI 도구의 임베드된 버전입니다. Swagger JSON을 해석하여 웹 API를 기능적으로 기술하는, 다양한 기능을 갖춘 사용자 정의식 경험을 빌드해 줍니다. 여기에는 공용 메서드에 대한 기본 제공 테스트 도구가 포함됩니다.
Swashbuckle CLI: 일단 설치되면 이 .NET 글로벌 도구를 사용하여 빌드/게시 중에 OpenAPI 사양을 생성할 수 있습니다. 이 모듈을 마치면 Swashbuckle CLI를 다운로드할 수 있는 링크가 있습니다.
이러한 라이브러리는 앱에 추가되어 API의 최신 버전으로부터 API 문서를 생성하고 시각화합니다. 항상 최신 코드와 동기화되는 라이브 문서를 만듭니다.