RAD서버 Swagger / YAML 및 RESTful API의 자체 문서화
2020.03.11 13:07
Stephen Ball 블로그 글 중에 REST API 클라이언트 개발에 큰 도움이 될만한 글이라 생각되어 번역(약간 내용 첨부)해보았습니다.
· 원문 링크 : https://delphiaball.co.uk/2016/04/22/swagger-yaml-delphi/
이 글은 ‘REST 서버와 클라이언트 개발하기’의 첫 번째 편입니다. RAD 서버와 함께 사용되는 Swagger UI 및 YAML 에 대해서 알아보겠습니다. 또한 이 글에 대한 업데이트 버전으로 RAD 서버의 새로운 기능을 다루는 게실물도 있습니다.
다음 글에서는 코드를 직접 사용하지 않고 TEMSDataSetResource 컴포넌트를 사용하여 RAD 서버의 마스터-디테일 데이터를 구현하는 방법에 대해서 다루도록 하겠습니다. 세번째 편에서는 델파이로 멀티 플랫폼 클라이언트를 작성해 보기로 하겠습니다.
Swagger / YAML 및 RESTful API의 자체 문서화
델파이로 Swagger를 시작하십시오.
새로운 REST 서버 (델파이 또는 C ++빌더를 사용하여)를 구축하여 다른 개발자들이 대중적으로 쉽게 사용할 수 있기를 원합니다. 아래와 같은 REST 서버 시나리오를 상상해보십시오.
새로운 REST 서버 구축
- 새로운 REST 서버 구축
- API를 문서화 해야합니다.
- 문서를 최신 상태로 유지 해야합니다
- 서비스 채택을 돕기 위해 다른 개발자가 서버에 빠르게 연결할 수 있는 예제를 작성하려고 합니다.
YAML이란 무엇입니까?
YAML : YAML Ain’t Markup Language의 약자입니다.
간단히 말해 YAML은 모든 프로그래밍 언어에 대해 사람이 쉽게 읽을 수 있는 데이터 직렬화 표준으로 직렬화(Data Serialization)란 구조화된 데이터를 특정 포맷으로 변환하는 개념입니다.
JSON과 YAML은 모두 가독성을 염두에 두고 설계된 포맷이지만 JSON과 YAML의 우선 순위가 다릅니다.JSON의 가장 중요한 디자인 목표는 단순성과 보편성입니다. JSON은 문법이 더 단순하기 때문에 적은 비용으로 생성하고 구문 분석 할 수 있습니다.
또한 가장 일반적인 공통 분모 정보 모델을 사용하므로 모든 최신 프로그래밍 환경에서 JSON 데이터를 쉽게 처리 할 수 있습니다.
반대로 YAML의 가장 중요한 디자인 목표는 가독성과 임의의 기본 데이터 구조를 직렬화하는데 있습니다.
따라서 YAML은 좀 더 가독성에 포커싱이 많이 되어있어만 JSON에 비해 생성 및 구문 분석이 더 복잡합니다. 또한 다른 프로그래밍 환경간에 서로 교류 할 때 처리가 좀 더 복잡합니다.
따라서 YAML은 JSON의 상위집합(SuperSet)으로 간주되어 가독성이 향상되고 보다 완전한 정보 모델이 제공됩니다. 실제로 모든 JSON 파일도 유효한 YAML 파일입니다. 따라서 추가 기능이 필요한 경우 JSON에서 YAML로 쉽게 마이그레이션 할 수 있습니다.
Swagger 란 무엇입니까?
Swagger는 RESTful API를 단순하면서도 강력하게 표현한 것으로, 오픈 툴인 이니셔티브 (2015 년 11 월 가입)의 일부로 Microsoft, Google, PayPal 및 IBM등에서 지원합니다.
YAML 문서를 사용하여 API의 Swagger 인스턴스를 작성할 수 있습니다.
전 세계의 가장 큰 API 툴링 시스템을 갖춘(사용하는) 수천 명의 개발자들은 거의 모든 최신 프로그래밍 언어 및 배포 환경에서 Swagger를 지원하므로 REST 서버를 다른 사용자가 쉽게 통합하고 사용할 수 있도록 하는 것이 좋습니다.
Swagger 지원 API를 사용하면 상호 대화식 문서, 클라이언트 SDK 생성 및 검색 기능등을 얻을 수 있습니다.
델파이 / C ++ 빌더로 YAML 생성
Swagger의 장점들을 이용하려면 YAML 문서를 작성해야합니다. 이는 생성중인 사용자 정의 API의 새로운 몇 가지 속성들을 사용하여 수행합니다. 세 가지 핵심 사용자 정의 API 문서 속성은 다음과 같습니다.
- Summary (EndPointRequestSummary)
- Parameters (EndPointRequestParameter)
- Details / Responses (EndPointResponseDetails)
사용자 정의 API 도큐멘테이션 샘플
Rad Studio 10.1 Berlin 이후 버전을 사용한다면 샘플에서 사용자 정의 API 도큐멘테이션 속성을 다루는 새로운 데모가 있습니다. 파일을 열려면 아래 폴더로 이동하여 APIDocDelphiAttributes.bpl 패키지를 여십시오.
\Samples\Delphi\Database\EMS\APIDocAttributes
이 샘플은 InterBase를 사용하므로 InterBase가 구동 되어 있는지 확인해야합니다. 실행 중이 아니면 IBServerManager를 사용하여 구동 해 주십시오.
여기에서 각 속성을 다루기 보다는 위의 링크를 참조하여 각 속성들을 파악 하겠습니다.대신 이 샘플을 사용하여 Swagger UI를 사용한 YAML을 검색합니다. 먼저 샘플을 실행하여 YAML 문서를 가져오겠습니다.
EMS 샘플에서 YAML 가져 오기
샘플 프로젝트를 컴파일하고 실행 (F9)하고 브라우저 열기를 선택하십시오. 아래와 같이 http ://localhost:8080/version에 대한 호출이 표시됩니다.
YAML에서 Swagger UI로 전환
이제 YAML 문서가 있습니다. 이제 무엇을 해야할까요? Swagger UI는 YAML 문서를 읽고 RESTful API에 대한 대화식 HTML 문서를 제공하는 훌륭한 도구입니다.
GitHub에서 최신 Swagger UI를 개발 시스템으로 다운로드 할 수 있습니다. https://github.com/swagger-api/swagger-ui.
개발 머신 /vm에 다운로드를 압축 해제하십시오. dist 폴더를 찾아 index.html을 여십시오.
CORS에 대한 메모
진행하기에 앞서 CORS – Cross Origin Resource Sharing에 대해서 알아야합니다.요컨데 핵심 도메인 외부에서 PUT, POST, DELETE를 사용하려면 CORS를 허용해야합니다.(CORS를 허용하지 않으면 EMS를 호출 할 수 없음).
CORS를 허용하도록 EMS 구성을 업데이트하거나 아래와 같이 Google 크롬 플러그인을 설치할 수 있습니다. 플러그인을 설치하는 경우, SwaggerUI index.html 페이지가 열리면 플러그인이 활성화되어 있는지 확인해야합니다. (때로는 작동하지 않도록 사용 중지했다가 재 사용하도록 설정해야 하는 경우도 있음).
크롬 플러그인을 사용하여 CORS 활성화
YAML을 Swagger에 로드
YAML 문서의 URL을 복사하여 SwaggerUI/dist/index.html 페이지에 게시하고 탐색을 선택하십시오.
SwaggerUI의 샘플(애완 동물 상점) 도큐먼트가 이제 EMS 서버 형식의 도큐먼트로 교체됩니다.
이제 SwaggerUI 인터페이스에서 직접 API 호출을 하고 조회 할 수 있습니다. 이 예제에서는 Sample Tag (카테고리가 표시됨)이라는 카테고리를 만듭니다. 다른 모든 카테고리에는 사용자 보안 및 새로운 ThingPoint EdgeModule API를 포함한 EMS의 기본 기능들이 포함됩니다.
Swagger UI에서 YAML 시각화
이제 카테고리를 탐색하고 리턴되는 구조를 정의하는 문서 모델을 검토 할 수 있습니다 (EndPointObjectXXX 속성 덕분에).
정의 된 매개 변수를 입력하고 "Try It Out"를 클릭하면 호출 된 URL과 응답 내용(본문)을 보여줍니다!
Swagger UI 사용해보기
이게 전부 입니다! RESTful API를 테스트하는 것이 얼마나 간단합니까?
이제 Swagger.IO를 검색하고 EMS 서버에 연결할 수 있는 다른 언어에 대해 알아볼 수 있습니다.
