RAD 서버 REST API의 문서와 API 테스트 제공하기(Swagger/YAML 기반)

[험프리]

Stephen Ball의 Swagger / YAML and Self Documenting RESTful API’s 을 번역했습니다.

델파이로 스웨거(Swagger) 지원

새로운 REST 서버(델파이 및 C++빌더 활용)를 구축하고, 다른 개발자들이 쉽고 편하기 사용되길 원할 것이다. 다음을 상상해 보자...

• 새로운 REST 서버 구축
• API를 문서화
• 문서를 최신 상태로 유지
• 서비스를 채택받기 위한 신속하게 연결 및 테스트할 수 있는 예제제공...

RAD 스튜디오 10.1 베를린 부터는 RAD 서버 패키지에서 스웨거(Swagger)와 함께 사용할 수 있는 YAML문서를 작성할 수 있다. 여러분의 API에 새로운 문서 속성(Attribute)을 추가하는 것만으로 위에 명시한 모든 작업을 수행할 수 있게되었다.

YAML이란 무엇인가?

YAML은 "YAML은 마크업 언어가 아니다(YAML Ain't Markup Language)"라는 재귀적인 이름에서 유래되었다.(참고: 위키백과)

간단히 말해 YAML은 모든 프로그래밍 언어에 대해 사람이 쉽게 읽을 수 있는 데이터 직렬화 표준이다.

JSON과 YAML은 모두 가독성을 염두에 두고 설계된 데이터 형식이지만, JSON과 YAM의 우선순위가 다르다. JSON의 가장 중요한 설계 목표는 단순성과 보편성이다. JSON은 사람의 가독성은 다소 낮지만 그 대가로 생성 및 구문 분석이 용이하다. 또한 가장 일반적인 정보 모델만을 사용해 대부분의 최신 프로그래밍 환경에서 쉽게 처리할 수 있다.

반대로 YAML의 가장 중요한 설계 목표는 사람의 가독성과 원본 데이터 구조를 그대로 직렬화하는 것을 지원한다. 따라서 YAML은 매우 읽기 쉽지만, 생성 및 분석은 더 복잡하다. 또한 YAML은 가장 일반적인 데이터 타입을 넘어, 다양한 프로그래밍 환경에서 사용 시 더 복잡한 처리가 필요한다.

따라서 YAML은 향상된 가독성과 더 완정한 정보 모델을 제공하는 JSON의 상위 집합(Superset)으로 볼수 있다. 셀제로 모든 JSON 파일도 YAML 파일의 범주에 포함되며, 추가 기능이 필요하다면 JSON을 YAML로 쉽게 마이그레이션 가능하다.

스웨거(Swagger)란 무엇인가?

스웨거는 RESTful API를 단순하면서도 강력하게 표현한 것이며, 공개 도구 이니셔티브(공개도구 사용 장례 단체, 2015년 11월 가입)의 일환으로 Microsoft, Google, PayPal 및 IBM등이 지원한다.

여러분의 API의 YAML 문서로 스웨거 인스턴스를 생성할 수 있다.(역자 주: 스웨거 문서에 YAML 문서를 등록해 API 문서를 제공할 수 있다.)

스웨거는 전세계 가장 큰 API 툴링 생태계로, 수천명의 개발자들이 대부분의 최신 프로그래밍 언어와 배포환경을 지원하므로, RAD 서버에 쉽게 통합하고 다른 사람들이 사용할 수 있도록 제공하는 것은 뛰어난 선택이다.

스웨거 지원 API는 상호 대화형 문서, 클라이언트 SDK 생성 및 검색 기능을 제공할 수 있다.

델파이/C++빌더로 YAML 만들기

스웨거의 이점을 얻으려면 YAML 문서를 만들어야 한다. 이 작업은 여러분들이 작성 중인 API의 선언에 여러가지 새로운 속성(Attribute)를 추가해야하며, 세가지 핵심 속성(Attribute)는 다음과 같다.

• Summary(EndPointRequestSummary)
• Parameters(EndPointRequestParameter)
• Details/Responses(EndPointResponseDetails)

또한 API에서 사용하는 EndPointObject를 정의할 수 있는 두가지 추가 문서 요소가 있다. 이 방법을 사용하면 단순한 타입을 반환하는 대신 반환되는 구조를 정의할 수 있다.

• EndPointObjectsYAMLDefinitions
• EndPointObjectsJSONDefinitions

사용자 정의 API 문서 샘플

(역자주: RAD 서버 개발환경 설정 후 진행하세요.)

RAD 스튜디오 10.1 베를린 이후 버전을 사용한다면 샘플에서 사용자 정의 API 문서 속성을 다루는 데모가 포함되어 있다. 다음 경로에서 APIDocDelphiAttributes.bpl 패키지를 오픈한다.

• C:\Users\Public\Documents\Embarcadero\Studio\{버전번호}\Samples\Object Pascal\Database\EMS\APIDocAttributes

이 글에서는 속성을 자세히 다루기 보다 직접 YAML을 만들고 스웨거 UI로 확인하는 과정을 설명한다.(위에서 안내한 링크를 참고해 자세한 설명을 확인할 수 있다.) 먼저 샘플을 실행해 YAML 문서를 확인해보자.

EMS 샘플에서 YAML 가져오기

샘플 프로젝트를 컴파일 및 실행(F9)하고 "Open Browser" 버튼을 눌르면, 웹브라우저에 http://localhost:8080/version 화면이 표시된다.(버전 번호 및 메시지는 버전에 따라 다를 수 있다.)

서버에서 문서를 가져오려면, http://localhost:8080/api로 이동하면 지원하는 다양한 문서 유형을 확인할 수 있다.

apidoc.yaml 및 apidoc.json 등 2가지 문서 유형을 제공하는 것을 확인할 수 있고, API url 끝에 추가해 문서내용을 확인할 수 있다.(예> http://localhost:8080/api/apidoc.yaml)

YAML을 스웨거 UI에서 보기

이제 YAML 문서가 준비되었다. 다음으로 스웨거 UI에서 YAML 문서를 연동해보자. 스웨거 UI는 YAML 문서를 편하게 읽을 수 있고, 대화형 HTML 문서를 제공하는 훌륭한 도구이다.

깃허브에서 최신 스웨거 UI를 다운로드 할 수 있다.

• https://github.com/swagger-api/swagger-ui

개발환경(또는 VM)에서 다운로드 후 압축을 해제한다. 이후 dist 폴더에서 index.html을연다.

CORS에 대한 참고사항

다음 진행 전 CORS(Cross Origin Resource Sharing)에 대해 알아야한다. 간단히 말하면 핵심 도메인 외부에서 PUT, POST, DELETE 연결을 활성화 하기 위해서는 CORS를 허용해야 한다.(허용하지 않으면 스웨거에서 RAD 서버를 호출할 수 없다.)

CORS를 허용하도록 EMS 구성을 업데이트 하거나 다음 구글 크롬 플러그인을 설치할 수 있다. 플러그인을 설치하는 경우 스웨거 UI index.html 페이지가 열리면 활성화 여부를 확인해야 한다.(가끔 비활성화되어, 다시 활성화해야 작동하는 경우가 있다.)

스웨거에서 YAML 불러오기

(앞에서 실행한 RAD 서버의)YAML 문서 URL을 복사 후 스웨거 UI에 붙여넣기 후 Explore 버튼을 누른다.

이제 스웨거 UI 인터페이스에서 API 인터페이스를 확인하고, API를 직접 호출할 수 있다. 

예시로는 샘플에 구현된 Sample Tag 카테고리로 확인한다.(기본 내장된 API에 대한 카테고리도 확인 및 호출할 수 있다.)

다음과 같이 호출 방법, 응답의 구조등의 문서 모델을 확인할 수 있다.(EndPointObjectXXX 속성에서 제공)

 

그리고, 전달할 파라미터 입력 후 "Try it Out"을 사용할 수 있다. 이것은 호출된 URL과 응답 바디등을 표시한다.

모든것을 확인해 보았다! YAML 및 스웨거 UI를 사용해 RESTful API를 테스트했다. 아마 이보다 더 간단히 할 수는 없을 것이다.

다음으로 swagger.io를 확인하면 RAD 서버에 연결할 수 있는 다른 도구들도 살펴볼 수 있다.