sgcOpenAPI는 팔레트 컴포넌트가 아니라 코드 생성기예요. 명세를 가리키면 Pascal 유닛 하나를 만들어 주고, 그 유닛을 프로젝트에서 호출하면 돼요. 이 페이지에서는 생성기를 한 번 실행한 다음, 생성된 클라이언트로 실제 호출을 해 봐요.
시작하기 전에 이해해야 할 단 하나가 이거예요. sgcOpenAPI는 IDE 팔레트에 아무것도 등록하지 않고, 디자인 타임 패키지도 포함하지 않아요. 작업 흐름은 생성한 다음 사용하는 거예요.
sgcOpenAPI.exe는 GUI 마법사이면서 명령줄이기도 해요. 명세를 읽고 .pas 파일 하나를 써요.
TsgcOpenAPI_Client에서 파생된 클라이언트 클래스, 작업마다 메서드 하나, 요청과 응답 클래스, 그리고 바로 쓸 수 있는 싱글턴을 반환하는 GetOpenAPIClient 함수가 들어 있는 유닛이에요.
생성된 유닛을 프로젝트에 추가하고 uses 절에 넣은 다음 GetOpenAPIClient.YourOperation(...)을 호출하세요. 결과는 응답 객체이며, 다 쓰면 직접 해제해야 해요.
AWS, Azure, Google, Microsoft용으로 미리 빌드된 SDK가 들어 있는 런타임 패키지 다섯 개가 포함되어 있어요. 컴파일용이지 설치용이 아니에요. 추가할 팔레트 페이지가 없기 때문이에요.
에디션 열은 코드를 제어하는 define이며, 제품 자체의 Source/sgcVer.inc에서 그 define이 있는 줄 번호도 함께 적었어요.
| 항목 | 값 |
|---|---|
| IDE | 생성된 코드는 Delphi 7부터 RAD Studio 13까지. 타입이 지정된 응답 객체는 XE7 이상이 필요하며, 포함된 데모는 {$IF CompilerVersion >= 28.0}으로 이를 가드해요. 그보다 낮은 버전에서는 생성된 메서드가 일반 문자열을 반환해요. |
| C++Builder | 생성된 클라이언트는 지원하지 않아요. sgcHTTP_OpenAPI_Client.pas 전체를 제어하는 SGC_HTTP_OPENAPI는 제품의 sgcVer.inc 702번째 줄의 {$IFNDEF BCB} 안에서 정의되므로, C++Builder 빌드에서는 그 유닛이 빈 코드로 컴파일돼요. |
| 에디션 | sgcOpenAPI 빌드는 가장 낮은 두 등급에 고정되어 있어요. sgcVer.inc의 7번째 줄부터 10번째 줄은 {$IFDEF SGC_OPENAPI} 다음에 {$UNDEF SGC_EDT_PRO}, {$UNDEF SGC_EDT_ENT}, {$UNDEF SGC_EDT_ALL}이 오고, Core와 Standard만 정의된 채로 남아요. 상용 등급은 기능이 아니라 사용자 수 기준이에요. |
| 서버 생성 | 같은 빌드가 11번째 줄에서 SGC_HTTP_OPENAPI_SERVER를 정의하므로 생성기는 클라이언트뿐 아니라 서버 스텁도 만들 수 있어요. 명령줄에 -s를 넘기세요. |
| 플랫폼 | 유닛 범위의 운영 체제 가드가 없어요. 생성된 클라이언트 기반 유닛 안의 조건문은 일반적인 {$IFDEF MSWINDOWS} import와 스레드 ID 타입 교체뿐이므로 Windows, macOS, Linux, Android, iOS 모두 컴파일돼요. |
| 라이선스 활성화 | 컴퓨터가 활성화되지 않았다면 명령줄에 -user와 -password를 넘기세요. 그러지 않으면 종료 코드 2로 끝나요. |
생성기는 JSON과 YAML을 받아들이며 둘 다 로컬에서 읽어요. Swagger 2.0 문서도 로컬에서 OpenAPI 3으로 변환돼요. 원격 변환기는 -r로 직접 켜야 하는 옵트인 방식이며 명세를 제3자 서버에 업로드하므로, 요청하지 않으면 꺼져 있어요.
설치할 디자인 타임 패키지가 없어서 다른 제품보다 설치가 짧아요.
다운로드한 파일을 폴더에 압축 해제하세요. 아래에서는 이 폴더를 {$DIR}이라고 불러요. Demos\, Bin\, Source\가 들어 있어요.
Tools, Options, Library로 이동해요. 생성된 유닛과 클라이언트 기반 클래스가 찾아지도록 {$DIR}\Source를 추가하세요. IDE에 설치할 것은 없어요.
함께 제공되는 SDK가 필요하면 {$DIR}\Packages\ 아래에서 해당 런타임 패키지를 열어 컴파일하세요. 런타임 패키지이므로 설치하지 말고 컴파일만 하세요.
마법사를 쓰려면 Bin\sgcOpenAPI.exe를 실행하고, 아니면 명령줄을 사용하세요. 입력 하나, 출력 하나면 유닛이 만들어져요.
생성된 .pas를 다른 유닛 옆에 두고 프로젝트에 추가한 뒤 uses 절에 넣으세요. 통합은 이게 전부예요.
명령줄 한 줄로 유닛을 생성하고, 호출 한 번으로 사용해요. 세 번째 탭은 첫날 알아 두면 좋은 옵션을 보여 줘요.
> sgcOpenAPI.exe -i "geolocation.json" -o "geolocation.pas"
File successfully created geolocation.pas두 옵션 모두 필수예요. -i는 로컬 파일이나 URL을 받으며 JSON과 YAML을 지원하고, -o는 생성할 Pascal 유닛이에요. 클릭이 더 편하다면 같은 실행 파일에 GUI 마법사도 있어요. 생성된 .pas를 프로젝트에 추가하면 바로 사용할 수 있어요.
uses
geolocation; // the unit you just generated
procedure TfrmGeolocation.btnGeolocationClick(Sender: TObject);
var
oResponse: TsgcOpenAPI_Retrieve_the_location_of_an_IP_address_Response;
begin
oResponse := GetOpenAPIClient.Retrieve_the_location_of_an_IP_address(
txtAPIKey.Text, txtIPAddress.Text);
try
if oResponse.IsSuccessful then
memoResponse.Lines.Text :=
'country: ' + oResponse.Successful.Country + #13#10 +
'city: ' + oResponse.Successful.City
else
memoResponse.Lines.Text := oResponse.ResponseError;
finally
oResponse.Free;
end;
end;GetOpenAPIClient는 유닛 안에 생성되며 매개변수가 없어요. 작업마다 메서드가 하나씩 있고, 이름은 작업 ID에서 따와요. 응답 객체는 직접 해제해야 하며, 그래서 데모가 try finally를 써요. XE7 이전의 Delphi 버전에서는 생성된 메서드가 일반 문자열을 반환하며, 포함된 데모는 타입이 지정된 경로를 {$IF CompilerVersion >= 28.0}으로 가드해요.
-s generate a server stub instead of a client
-a 3 add an OAuth2 flow to the generated client
(0 none, 1 basic, 2 token, 3 oauth2, 4 jwt)
-u <url> set the base url the generated client uses
-m 1 name methods from summary rather than operationid
(0 operationid, 1 summary, 2 endpoint)
-x <list|file> exclude operations, as "VERB endpoint"
-p generate only the classes the kept operations use
-nc do not create pascal classes
-l show progress messages (errors are always shown)
-user -password activate the licence on this machine큰 명세에서는 -x와 -p를 함께 쓰는 것이 IDE에서 열 수 있는 유닛과 열 수 없는 유닛의 차이를 만들어요. -r도 있지만 명세 전체를 제3자 변환기에 업로드하기 때문에 의도적으로 기본값이 꺼져 있어요.
생성 명령은 도구 자체 도움말이 출력하는 사용법 줄이에요. 호출 부분은 포함된 데모 Demos\20.Client\abstractapi.com\geolocation\fGeolocation.pas이며 폼 컨트롤은 리터럴로 바꿨어요. 그 데모는 명세만 포함하고 유닛은 직접 생성하도록 되어 있어서, 빠른 시작이 생성기로 시작하는 거예요.
확인할 것이 두 가지 있고, 그중 하나는 스크립트로 처리할 수 있어요.
도구는 File successfully created와 출력 경로를 출력해요. 오류는 항상 표준 오류로 나가므로, 아무것도 쓰지 않은 조용한 실행이 무음은 아니에요.
0 성공, 1 오류, 2 잘못된 라이선스, 3 잘못된 옵션, 4 잘못된 설정 파일, 5 잘못된 입력 파일, 6 잘못된 출력 파일, 7 명세를 올바른 OpenAPI 3 문서로 변환할 수 없음. 빌드 스크립트에서 검사하세요.
생성된 .pas를 프로젝트에 추가하고 빌드하세요. 라이브러리 경로의 {$DIR}\Source 외에는 아무것도 없어도 컴파일되어야 해요.
IsSuccessful런타임에는 응답 객체가 알려 줘요. false이면 ResponseError에 메시지가, ResponseCode에 HTTP 상태가 담겨 있어요.
첫 실행의 문제는 거의 다 여섯 가지 중 하나가 원인이에요.
없어요. sgcOpenAPI는 컴포넌트를 등록하지 않고 디자인 타임 패키지도 포함하지 않아요. 생성된 유닛이 통합 지점이고, 클라이언트에 접근하는 방법은 GetOpenAPIClient예요.
정상이에요. 데모는 생성된 유닛이 아니라 명세만 포함하므로 먼저 생성기를 실행해야 해요. geolocation 데모에는 geolocation이라는 유닛이 필요하며, 이는 geolocation.json에서 만들어져요.
이 컴퓨터에서 라이선스가 활성화되지 않았어요. 명령줄에 -user와 -password를 넘기세요.
타입이 지정된 응답은 XE7 이상이 필요해요. 포함된 데모는 {$IF CompilerVersion >= 28.0}으로 가드하고 더 오래된 컴파일러에서는 일반 문자열을 반환하는 메서드로 대체해요. Delphi 7을 지원한다면 그 가드를 유지하세요.
SGC_HTTP_OPENAPI는 제품의 sgcVer.inc 702번째 줄의 {$IFNDEF BCB} 안에서 정의되므로, 생성된 클라이언트 기반 클래스는 C++Builder에서 전혀 컴파일되지 않아요.
종료 코드 7은 문서를 올바른 OpenAPI 3 문서로 바꿀 수 없다는 뜻이에요. YAML과 Swagger 2.0은 로컬에서 처리해요. -r 뒤의 원격 변환기는 최후의 수단이며, eSeGeCe가 관리하지 않는 서버에 파일 전체를 업로드해요.
같은 생성기에서 시작하는 네 가지 방향이 있어요.
-s를 넘기면 생성기가 서버 스텁을 만들어요. 서버 데모는 생성된 작업이 어떻게 디스패치되고 명세에 맞게 검증되는지 보여 줘요.
AWS, Azure, Google, Microsoft를 포함해 천 개가 넘는 명세가 이미 생성되어 제공돼요. 원하는 패키지를 컴파일하면 생성 단계를 완전히 건너뛸 수 있어요.
-x는 동사와 엔드포인트로 작업을 제외하고, -p는 남은 작업이 쓰지 않는 클래스를 제거해요. 큰 명세에서는 열 수 있는 유닛과 열 수 없는 유닛의 차이가 돼요.
생성된 클라이언트에는 Authentication 속성이 있고, -a가 생성 시점에 방식을 선택해요. 없음, 기본, 토큰, OAuth2, JWT 중 하나예요.
데모 프로젝트는 다운로드 안의 Demos\ 아래에 있어요. 미리 빌드된 SDK, 생성된 클라이언트 하나, 서버 샘플 두 개예요.
| sgcOpenAPI가 하는 일 파서, 생성기, 서버 컴포넌트를 한 페이지에서 소개해요. | 열기 | |
| 파서 명세를 읽고, 검증하고, Pascal 타입으로 바꾸는 방법. | 열기 | |
| 서버 컴포넌트 명세를 사용하는 대신 명세로부터 API를 제공하는 방법. | 열기 | |
| 포함된 API 바로 컴파일할 수 있게 제공되는 미리 빌드된 SDK. | 열기 | |
| 체험판 다운로드 생성기와 소스, 기간 제한이 있어요. | 열기 | |
| OpenAPI란? 명세 형식 자체가 낯설다면 읽어 볼 배경 설명. | 열기 |
함께 읽어 보세요. OpenAPI에서 Delphi 클라이언트 생성하기, 스키마 번들링, sgcOpenAPI와 swagger-codegen 비교, OpenAPI 서버. 모든 제품에는 각자의 빠른 시작이 있으며, 시작하기 페이지에서 모아 볼 수 있어요.
sgcOpenAPI.exe를 실행하면 Pascal 유닛 하나가 만들어지고, 그 유닛을 프로젝트에 추가하면 돼요. 그 안의 GetOpenAPIClient는 작업마다 메서드가 하나씩 있는, 바로 쓸 수 있는 클라이언트 객체를 반환해요.
sgcOpenAPI.exe -i "c:\openapi.json" -o "c:\openapi.pas"예요. 두 옵션 모두 필수예요. -i는 로컬 파일이나 URL을 받고 JSON과 YAML을 모두 지원해요. -o는 생성할 Pascal 유닛이에요. -i:"c:\openapi.json"처럼 콜론 뒤에 값을 붙일 수도 있어요.
TsgcOpenAPIResponse에서 파생된 응답 객체를 반환해요. 먼저 IsSuccessful을 읽으세요. false이면 ResponseError에 메시지가, ResponseCode에 HTTP 상태가 담겨 있어요. 다 쓰면 응답 객체를 해제하세요. 포함된 데모는 try finally로 해제해요.
sgcHTTP_OpenAPI_Client.pas의 인터페이스 전체를 감싸는 SGC_HTTP_OPENAPI가 제품의 sgcVer.inc 702번째 줄의 {$IFNDEF BCB} 안에서 정의되므로, C++Builder에서는 그 유닛이 빈 코드로 컴파일되어 생성된 코드에 기반 클래스가 없어요. Delphi용으로 생성하세요.
{$IF CompilerVersion >= 28.0}으로 그것을 분명히 해요. 그 기준 이상에서는 타입이 지정된 필드가 있는 응답 객체를 받고, 그 미만에서는 같은 메서드가 일반 문자열을 반환해요. 프로젝트가 두 환경 모두에서 빌드되어야 한다면 가드를 유지하세요.
-s를 넘기면 생성기가 클라이언트 대신 코드 우선 어트리뷰트가 있는 서버 스텁을 만들어요. sgcOpenAPI로 제공되는 빌드는 sgcVer.inc의 11번째 줄에서 SGC_HTTP_OPENAPI_SERVER를 정의하므로 서버 측은 모든 라이선스에 포함돼요. 서버 데모 두 개가 Demos\30.Server 아래에 들어 있어요.
-r 옵션은 converter.swagger.io의 공개 변환기로 대체하는 것을 허용하며, 도움말에도 이것이 eSeGeCe가 관리하지 않는 서버에 파일 전체를 업로드한다고 분명히 적혀 있어요. 기밀 문서에는 꺼 두세요.