Swagger란?

정의

Swagger란 웹 서비스의 API 문서를 작성, 빌드 및 시각화하기 위한 도구 및 표준.
API( Application Programing interface ) 는 소프트웨어 애플리케이션 간에 상호작용하는 방법을 정의하는 규약이다.
Swagger는 개발자가 API를 설계하고 문서화하며, 클라이언트 개발자들이 이해하기 쉽게 API와 상호작용할 수 있도록 도와줍니다.
Swagger는 주로 OAS( OpenAPI Specification )이라는 스펙을 따릅니다. OAS는 API의 구조, 엔드포인트, 매개변수, 응답형식 등을 정의하는 JSON 또는 YAML 형식의 파일입니다. Swagger 도구를 사용하면 이런 OAS 파일을 작성하고, 이를 기반으로 자동으로 API 문서를 생성할 수 있습니다.

 

Swagger 이미지

https://static1.smartbear.co/swagger/media/images/tools/swaggerhub/sh-wow-hosted-interactive-api-documentation.png?ext=.png

 

장점

• API의 청사진을 매핑하는 친숙한 사용자 인터페이스가 있습니다.
• 설명서는 개발자와 고객 또는 프로젝트 관리자와 같은 비개발자 모두가 이해할 수 있습니다.
• 사양은 사람과 기계가 읽을 수 있습니다.
• 쉽게 테스트할 수 있는 대화형 문서를 생성합니다.
• 40개 이상의 언어로 된 API 라이브러리 생성을 지원합니다.
• 형식은 JSON 및 YAML에서 사용할 수 있으므로 편집이 용이합니다.
• API 관련 프로세스를 자동화하도록 지원합니다.

Swagger 편집기

https://editor.swagger.io/

Swagger Editor

스웨거 편집기를 이용해서 HTML 페이지로 변환해 전달하거나 문서 자체를 전달 할 수 있다.

 

3줄 요약

실제 API 호출 시 문서를 참조하여 response 구조를 확인해야 할 때가 많은 데 API를 구성할 때 Swagger 문서를 작성 해 놓으면 개발자가 사용하기 편리하고, 시인성이 있으며, 인수인계 시에도 API를 빠르게 이해시키고 테스트 하게 끔 도와주는 문서

 

 

[참조]

https://blog.hubspot.com/website/what-is-swagger

https://swagger.io/tools/swagger-ui/