알림
RESTful API 문서 테스트 자동화를 위한 Swagger 소개
안녕하세요. 시니어 개발자 에디입니다.
백엔드 개발언어의 종류를 떠나 백엔드 시스템에서 제공해야하는 핵심 기능으로는 주로 RESTFul API 서비스 를 구현해서 프론트엔드 또는 이기종 시스템간의 데이터 연동과 시스템 통합을 위한 기능을 제공해야합니다.
프론트엔드/백엔드로 구분하여 하나의 서비스를 개발하는 환경이나 또는 다른 업체/고객사/동일 회사내의 다양한 시스템들간의 데이터 연동을 위해 백엔드 개발자들은 각종 백엔드 개발언어와 백엔드 개발 프레임워크등을 기반으로 RESTFul API를 구현합니다.
일반적으로 RESTFul API 서비스는 구현된 API를 사용하는 측(클라이언트,고객사,프론트엔드)과 개발 제공하는 측(데이터제공업체,백엔드)으로 나뉘어지기에 필연적으로 협업이 발생하게되며 백엔드에서 제공하는 RESTFul API들의 목록과 제공기능,사용법등을 사용하는 측에 어떤식으로든 사전 공유해줘야 원할한 협업 개발이 진행됩니다.
1) Swagger 소개
백엔드에서 개발된 각종 API 기능목록과 사용법을 전통적인 엑셀등과 같은 API명세표 문서를 작성해서 상호 공유해서 사용하는 방법들도 여전히 많이 사용되긴 하지만 소스형태로 개발된 REST API 기능을 소스상에 최소한의 작업을 통해 API 문서를 웹페이지 형태로 자동화 생성하고 테스트 환경을 제공할수 있다면 보다 원할하고 편리한 협업 환경 제공 및 향후 시스템의 유지보수에도 많은 도움이 됩니다.
이러한 시스템 개발의 니즈를 위해 나온 SW 서비스중 하나가 Swagger(스웨거)이며 대부분의 현대적 백엔드 개발언어/프레임워크의 모든 개발/서비스 환경에서는 Swagger를 채택해 API문서의 자동화 및 손쉬운 테스트 환경을 제공하고 있습니다.
Swagger는 백엔드 개발 언어가 인터프리팅 언어(파이썬,노드,PHP) 이던 컴파일 언어(C#,JAVA,..)이던 상관없이 손쉽게 언어별 Swagger 오픈소스 패키지(라이브러리)를 개발소스에 다운받아 설치후 간단한 설정과정을 통해 손쉽게 개발자가 사용할수 있게 관련 기능을 제공하고 있습니다.
이번 블로깅에서는 Node Express 환경에서의 데이터 처리 등록/수정/삭제/조회 RESTFul API를 빠르게 만들어보고 해당 API들을 Swagger를 통해 API문서를 자동화하고 제공된 API DOCS 웹페이지 문서를 통해 테스트 하는 기초 과정을 안내해 드립니다.
Swagger기초 과정을 통해 기본 사용법을 익히고 단계적으로 사용자 인증 기반(Bearer Token) API 문서 자동화 테스트도 진행예정이며 주요 개발언어별 Swagger 사용법들도 단계적으로 소개해드릴 예정이오니 참고바랍니다.
2) Open API Specification(OAS) 소개
Swagger사용에 앞서 먼저 개발자라면 OpenAPI 란 용어에 대한 이해가 필수입니다.
흔히 개발자나 일반인분들이 알고계시는 OpenAPI라 함은 정보를 제공해주는 각종 서비스/시스템(공공데이터포탈,기상청..서비스제공업체 등등)에서 무료로 제공해주는 RESTFul API 데이터 서비스등을 통칭해서 OpenAPI라고 말하지만 또 다른 의미로 사용되는 경우도 있는데요.
RESTful API를 구현할떄 지켜야 하는 규칙과 스펙등을 정의하는 표준기술을 OpenAPI 라고도 합니다.
즉 RESTful API 설계 정의 표준을 OpenAPI라고도 말하며 전문용어로는 Open API Specification(OAS)라고 합니다.
https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md
Swagger는 RESTFul API의 문서 자동화를 기본제공하므로 문서를 생성하거나 테스트를 위해 제공되는 형식들은 반드시 Open API Specification(OAS) 표준을 기반으로 만들어지고 서비스되며 현재 Swagger는 2.0,3.0 두가지 버전이 제공되고 있으며 각각의 버전은 OAS 2.0/ OAS3.0 표준을 준수해서 서비스가 제공되고 있습니다.
OAS는 기본적으로 개발자가 개발 제공하는 각종 RESTful 서비스 스펙을 json 또는 yaml 파일 형식으로 손쉽게 표현하고 구성할수 있는 환경을 제공합니다.
OAS 2.0 기반으로 또는 OAS3.0 기반으로 RESTful API 서비스 스펙을 기술하는 방식이 다소 상이하므로
여러분의 프로젝트에서 OAS2.0을 사용할지, 3.0을 사용할지에 대해 정의를 분명히 하고 해당 버전 문법으로 JSON 또는 yaml파일/주석형식을 통해 RESTFul API 기능들을 명세하시면 됩니다.
Swagger 자체를 개발하고 서비스하면서 사용한 기본 API 명세기술을 표준화하여 표준기술로 공개한 기술표준을 OAS라고 이해하시면 좋을듯하고 Swagger는 구체적인 API 문서자동화 및 테스팅 환경제공 도구이고 OAS는 Swagger에서 개발자가 만든 API를 명세시 준수해야하는 표준기술 스펙으로 이해하면 좋을듯합니다.
HTML5,CSS3와 해당 언어의 표준스펙을 관리해주는 W3C의 표준 스펙과의 관계정도로 이해하시면 좋지 않을지 싶네요.
3) Swagger Docs 주요 버전 소개
Swagger는 2010년대 초중반부터 본격 사용되기 시작하면서 2015년 SmartBear라는 회사에서 Swagger를 인수하여 현재 해당 회사에서 개발 제공하는 오픈소스 API 문서자동화 /테스팅 SW이며 각종 편리 기능을 포함한 유료버전 또한 제공되고 있습니다.
아래 링크를 확인해보시면 Specification V2.0 And Specification V3.0 링크가 제공되는데요.
해당 링크에서 각 버전별 기본 사용법을 안내하고 있으니 참고하시기 바랍니다.
https://swagger.io/docs/
4) Swagger 사용 목적
그럼 백엔드 개발자분들이 RESTFul API를 개발할때 반드시 Swagger를 사용해야할까요?
어떠한 기술을 사용할때는 반드시 왜? 무엇떄문에 어떤용도로 해당 기술을 사용해야하는지 분명히 알고 사용하실것을 권장드립니다.
Swagger를 사용해야하는 주요목적으로 두가지만 언급하겠습니다
첫쨰, RESTful API 기능 명세 문서 자동화 기능
위에서도 말한대로 개발자가 개발한 API 기능을 구글 워크시트나 엑셀문서,워드 문서등으로 정리해 공유할수도 있지만 기능 변경 관리, 실시간 협업,소스와의 통합을 통한 지속적인 시스템 유지보수 관리가 필요하다면 Swagger는 필수적으로 사용하는것이 좋습니다.
둘째, Swagger UI를 통한 테스팅 환경 제공
보통 백엔드 개발자가 개발한 RESTful API는 반드시 사전 테스트 과정을 통해 정상적으로 API가 작동하는지 검증하는 과정이 필수적으로 수행되어야하며 보통 테스트 환경은 UI환경을 통해서 API를 호출하거나 또는 PostMan과 같은 API 테스팅 클라이언트 툴/서비스등을 통해 테스트가 진행됩니다.
일반적으로 UI개발이 완료되기전까지는 Postman등을 통해 테스트하지만 테스트를 위해 별도 설치 또는 서비스 신청(무료)과정을 거쳐야하지만 Swagger는 문서 자동화 뿐만 아니라 웹페이지 문서형태로 동일한 백엔드 서비스환경을 통해 테스팅 UI 환경을 자동으로 제공합니다.
즉, Postman등을 사용하지 않고도 Swagger에서 제공하는 UI 웹페이지 를 통해 다양한 데이터 형식 정의 및 데이터 전달 및 반환 결과 확인이 가능합니다.
물론 원할한 테스트 UI환경 제공을 위해 json이나 yaml 문서 또는 직접 주석처리를 통해 각각 API에 전달되는 데이터 형식 및 반환형식,모델 형식(Swagger Components)등을 정의해줘야하는 번거로움등이 있긴하지만 한번 정의해두고 재사용할수 있고 API에대한 입출력 형식을 정확히 사용하는측에 전달할수 있어 문서파일로 작성하는것보다는 훨씬 효울적입니다.
자~ 다음 시간에는
Node Express RESTful API 프로젝트를 하나 만들고 데이터 C/R/U/D API기능을 가볍게 구현해 본 후 Swagger를 통한 API 문서 및 테스트 자동화 환경을 구성해보도록 하겠습니다.
다음 단계 : Node Express RESTful API 프로젝트 만들기
