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를 문서화 해야합니다.
  • 문서를 최신 상태로 유지 해야합니다
  • 서비스 채택을 돕기 위해 다른 개발자가 서버에 빠르게 연결할 수 있는 예제를 작성하려고 합니다.
RAD Studio 10.1 Berlin이 출시되면서  EMS 패키지에서 Swagger와 함께 사용할 수 있는 YAML 문서를 작성할 수 있으며 사용 되는 새로운 문서 속성 덕분에 위에 명시한 모든 작업을 수행 할 수 있습니다.
 

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 문서 속성은 다음과 같습니다.

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

 

사용자 정의 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에 대한 호출이 표시됩니다.

 
EMS-Version-300x100.png
 
서버에서 도큐먼트를 받으려면 http://localhost:8080/api로 이동하여 지원되는 다양한 문서 유형을 볼 수 있습니다.
 
EMS-API-300x92.png
 
현재 apidoc.yaml 및 apidoc.json등 2 개가 표시됩니다. API URL 끝에 예 : http://localhost:8080/api/apidoc.yaml 과 같이 추가하여  확인하십시오. 
 
EMS-APIDoc-YAML--300x226.png

 

http://localhost:8080/api/apidoc.yaml EMS에서 Swagger와 함께 사용하여 YAML을 반환
 

YAML에서  Swagger UI로 전환

 

이제 YAML 문서가 있습니다. 이제 무엇을 해야할까요? Swagger UI는 YAML 문서를 읽고 RESTful API에 대한 대화식 HTML 문서를 제공하는 훌륭한 도구입니다.

 

GitHub에서 최신 Swagger UI를 개발 시스템으로 다운로드 할 수 있습니다. https://github.com/swagger-api/swagger-ui.

 
Download-Swagger-UI-300x138.png

 

 

개발 머신 /vm에 다운로드를 압축 해제하십시오. dist 폴더를 찾아 index.html을 여십시오.

 

CORS에 대한 메모

 

진행하기에 앞서 CORS – Cross Origin Resource Sharing에 대해서 알아야합니다.요컨데 핵심 도메인 외부에서 PUT, POST, DELETE를 사용하려면 CORS를 허용해야합니다.(CORS를 허용하지 않으면 EMS를 호출 할 수 없음).

 

CORS를 허용하도록 EMS 구성을 업데이트하거나 아래와 같이 Google 크롬 플러그인을 설치할 수 있습니다. 플러그인을 설치하는 경우, SwaggerUI index.html 페이지가 열리면 플러그인이 활성화되어 있는지 확인해야합니다. (때로는 작동하지 않도록 사용 중지했다가 재 사용하도록 설정해야 하는 경우도 있음).

 
Enabling-CORS-286x300.png

   크롬 플러그인을 사용하여 CORS 활성화

 

YAML을 Swagger에 로드

 

YAML 문서의 URL을 복사하여 SwaggerUI/dist/index.html 페이지에 게시하고 탐색을 선택하십시오.

 

SwaggerUI의 샘플(애완 동물 상점) 도큐먼트가 이제 EMS 서버 형식의 도큐먼트로 교체됩니다.

 

이제 SwaggerUI 인터페이스에서 직접 API 호출을 하고 조회 할 수 있습니다. 이 예제에서는 Sample Tag (카테고리가 표시됨)이라는 카테고리를 만듭니다. 다른 모든 카테고리에는 사용자 보안 및 새로운 ThingPoint EdgeModule API를 포함한 EMS의 기본 기능들이 포함됩니다. 

 
EMS-Yaml-in-Swagger-300x244.png

 

 Swagger UI에서 YAML 시각화

 
 
Viewing-Swagger-UI-exposed-Methods-300x278.png

 

이제 카테고리를 탐색하고 리턴되는 구조를 정의하는 문서 모델을 검토 할 수 있습니다 (EndPointObjectXXX 속성 덕분에).

 

정의 된 매개 변수를 입력하고 "Try It Out"를 클릭하면 호출 된 URL과 응답 내용(본문)을 보여줍니다!

 

Trying-out-Swagger-UI-749x1024.png

 Swagger UI 사용해보기

 

이게 전부 입니다!  RESTful API를 테스트하는 것이 얼마나 간단합니까?

 

이제 Swagger.IO를 검색하고 EMS 서버에 연결할 수 있는 다른 언어에 대해 알아볼 수 있습니다.

번호 제목 글쓴이 날짜 조회 수
공지 [DelphiCon 요약] 코드사이트 로깅 실전 활용 기법 (Real-world CodeSite Logging Techniques) 관리자 2021.01.19 7316
공지 [UX Summit 요약] 오른쪽 클릭은 옳다 (Right Click is Right) 관리자 2020.11.16 7083
공지 [10.4 시드니] What's NEW! 신기능 자세히 보기 관리자 2020.05.27 9481
공지 RAD스튜디오(델파이,C++빌더) - 고객 사례 목록 관리자 2018.10.23 14553
공지 [데브기어 컨설팅] 모바일 앱 & 업그레이드 마이그레이션 [1] 관리자 2017.02.06 16288
공지 [전체 목록] 이 달의 기술자료 & 기술레터 관리자 2017.02.06 12049
공지 RAD스튜디오(델파이, C++빌더) - 시작하기 [1] 관리자 2015.06.30 31388
공지 RAD스튜디오(델파이,C++빌더) - 모바일 앱 개발 사례 (2020년 11월 업데이트 됨) 험프리 2014.01.16 167007
23 윈도우 & 리눅스에 RAD서버 손쉽게 배포하기 관리자 2021.04.12 360
22 RAD 서버 : 웹 속성을 폴더에 매핑하기 file 김원경 2020.03.17 1462
» Swagger / YAML 및 RESTful API의 자체 문서화 김원경 2020.03.11 835
20 RAD 서버에 Swagger UI 임베이딩 김원경 2020.03.09 415
19 TEMSDataSetResource 컴포넌트를 사용하여 RAD 서버의 마스터-디테일 데이터 구현하기 file 김원경 2020.03.06 309
18 RAD서버 도커(Docker) 기술 가이드 관리자 2020.02.26 275
17 RAD 서버 완벽 가이드 - 200페이지 분량의 전자책 file 험프리 2020.02.07 626
16 RAD서버에서 데이터를 JSON으로 어떻게 오픈할 수 있을까요? (JSONValue와 JSONWriter 활용하기) 관리자 2020.01.21 234
15 RAD서버 활용하기 (엠바카데로 아카데미 코스) 관리자 2020.01.06 244
14 [RAD서버] JSON 처리 단순화 컴포넌트 활용 - TEMSDataSetResource 험프리 2019.09.27 637
13 [10.3 리오][업데이트 2] 새로운 RAD서버 관리 콘솔 관리자 2019.08.28 495
12 리눅스에 RAD서버 배포하기 관리자 2019.07.11 369
11 기존 시스템을 웹(Web)으로 확장하기 위해 고려해야 할 두 가지 포인트 관리자 2018.06.11 1255
10 델파이/C++빌더 개발자를 위한 웹 개발 with ExtJS! 관리자 2018.06.04 836
9 RAD서버 솔루션 시리즈: 필드 서비스 애플리케이션 관리자 2018.06.01 512
8 Ext JS 활용과 앞으로의 방향 관리자 2018.05.24 1070
7 센차 ExtJS 웹 클라이언트 + RAD서버 10.2.3 관리자 2018.04.24 1251
6 [10.2 도쿄][릴리즈3] RAD서버에서 센차 Ext JS 지원 확장 관리자 2018.03.30 429
5 [발표자료] 2018022 마이크로서비스 아키텍처 구현과 활용 with RAD서버 file 관리자 2018.02.23 365
4 RAD서버로 개발은 확장하면서도 비용을 절감하는 방법 (RAD서버 라이선스 유형별 정리) file 관리자 2017.06.20 1454