Stripe는 자사 API의 공식 OpenAPI 3 설명을 게시하고 유지 관리해요. sgcOpenAPI는 손으로 작성한 Stripe 컴포넌트를 제공하지 않아요. 대신 생성기를 제공해요. 그 사양에 sgcOpenAPI.exe를 한 번 실행하면 오퍼레이션마다 메서드 하나, 그 각각에 타입이 지정된 응답 클래스 하나, 그리고 바로 쓸 수 있는 클라이언트를 돌려주는 GetOpenAPIClient 함수를 담은 Pascal 유닛 하나가 나와요.
아래 수치는 현재 spec3.json에 생성기를 실행하고 결과를 컴파일해서 측정한 값이에요. 추정치가 아니에요.
github.com/stripe/openapi의 openapi/spec3.json이고 OpenAPI 3.0.0으로 선언되어 있어요. 변환 단계는 필요 없어요.
419개의 경로가 594개의 메서드와 594개의 응답 클래스가 되고, 여기에 1,747개의 모델 클래스가 더해져 약 110,000줄짜리 유닛 하나가 나와요.
-a 2로 생성하고 런타임에 Authentication.Token.BearerToken을 설정하세요. 그러면 클라이언트가 모든 요청에 Authorization: Bearer를 보내요.
생성된 유닛은 RAD Studio 12의 Win32에서 라이브러리 경로에 sgcOpenAPI Source 폴더 말고는 아무것도 없이 깨끗하게 빌드돼요.
Stripe의 공개 저장소에서 spec3.json을 다운로드하거나, 원본 URL을 -i에 그대로 넘기세요. 이 두 스위치는 필수이고 나머지는 모두 기본값이 있어요.
> sgcOpenAPI.exe -i "spec3.json" -o "stripe.pas" -a 2 File successfully created stripe.pas
-i는 로컬 파일이나 URL을 받고 JSON과 YAML을 모두 인식해요. -o는 작성할 Pascal 유닛이고, 유닛 이름은 그 파일 이름을 따라요. -a 2는 토큰 인증을 선택하는데, Stripe의 시크릿 키에 필요한 방식이에요. 같은 실행 파일을 매개변수 없이 시작하면 GUI 마법사로 동작해요. 성공하면 종료 코드 0으로 끝나고, 빌드 스크립트는 5(입력 파일), 6(출력 파일), 7(문서를 유효한 OpenAPI 3 문서로 바꿀 수 없음)을 확인할 수 있어요.
생성된 .pas를 프로젝트에 추가하고 uses 절에 넣으면 통합은 그것으로 끝이에요. sgcOpenAPI는 컴포넌트를 등록하지 않고 디자인타임 패키지도 제공하지 않기 때문에, 설치할 컴포넌트가 없어요.
시크릿 키를 클라이언트에 한 번 설정한 다음, 생성기가 오퍼레이션 id를 따라 이름 붙인 메서드를 호출하세요. Stripe의 오퍼레이션 id는 이미 유효한 Pascal 식별자라서 PostCharges가 그대로 나와요.
uses stripe; // 방금 생성한 유닛 procedure TfrmStripe.btnChargeClick(Sender: TObject); var oResponse: TsgcOpenAPI_PostCharges_Response; begin GetOpenAPIClient.Authentication.Token.BearerToken := 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'; oResponse := GetOpenAPIClient.PostCharges( 'amount=2000¤cy=usd&source=tok_visa&description=Order+1234'); try if oResponse.IsSuccessful then memoLog.Lines.Text := 'charge : ' + oResponse.Successful.Id + #13#10 + 'status : ' + oResponse.Successful.Status + #13#10 + 'paid : ' + BoolToStr(oResponse.Successful.Paid, True) else memoLog.Lines.Text := IntToStr(oResponse.ResponseCode) + ' ' + oResponse.ResponseError; finally oResponse.Free; end; end;
GetOpenAPIClient는 매개변수를 받지 않고, 직접 해제하지 않는 클라이언트를 돌려줘요. 기본 URL은 사양의 servers 항목에서 나오기 때문에 생성된 생성자가 이미 https://api.stripe.com/을 설정해 두고, 생성 시점의 -u나 런타임의 SetBaseURL로만 바꾸면 돼요. 응답 객체는 호출한 쪽 소유라서 예제가 try finally를 쓰고 있어요. IsSuccessful은 상태 200부터 299까지 true이고, 나머지는 ResponseCode와 ResponseError가 알려 줘요.
Stripe에서 사람들이 가장 의외로 여기는 부분인데, 생성기가 아니라 사양에서 비롯된 거예요.
var oCustomer: TsgcOpenAPI_PostCustomers_Response; oSub: TsgcOpenAPI_PostSubscriptions_Response; begin oCustomer := GetOpenAPIClient.PostCustomers( 'email=jane@example.com&payment_method=pm_card_visa'); try if not oCustomer.IsSuccessful then raise Exception.Create(oCustomer.ResponseError); oSub := GetOpenAPIClient.PostSubscriptions( 'customer=' + oCustomer.Successful.Id + '&items[0][price]=price_1JxYzZAbCdEfGhIj'); try memoLog.Lines.Add(oSub.Successful.Id); finally oSub.Free; end; finally oCustomer.Free; end; end;
Stripe 사양에 있는 593개의 요청 본문은 하나도 빠짐없이 application/x-www-form-urlencoded로 선언되어 있어요. 그래서 생성된 매개변수는 const aBody: string이고, 폼은 Stripe 고유의 대괄호 표기법으로 직접 만들게 돼요. 응답은 이야기가 달라요. 이름이 붙은 스키마로 선언되어 있어서 각각 속성으로 읽는 클래스가 돼요.
유닛은 문서를 그대로 반영해요. 따로 선별하지 않기 때문에 Stripe가 설명한 것은 모두 들어 있고, Stripe가 빠뜨린 것은 들어 있지 않아요.
594개가 있고, Pascal 식별자에 쓸 수 없는 문자를 뺀 오퍼레이션 id에서 이름을 따요. -m 1은 요약에서, -m 2는 엔드포인트에서 이름을 지어요.
TsgcOpenAPI_PostCharges_Response는 TsgcOpenAPIResponse를 상속하고, Successful과 선언된 오류 상태마다 속성 하나를 가지며, IsSuccessful, ResponseCode, ResponseError를 물려받아요.
Stripe가 선언한 모든 스키마가 들어 있어요. 공용 error 객체, charge, customer, invoice, subscription 객체, 그리고 이벤트 페이로드까지요.
선택적 쿼리 매개변수는 선언 순서대로 기본값이 있는 인자가 돼요. 그래서 GetCharges는 URL을 건드리지 않고도 aCreated, aCustomer, aEnding_before, aExpand, aLimit 등을 받아요.
문서의 태그는 하나뿐인 클래스 안에서 메서드를 묶어 주는 주석으로 나와요. 별도의 클래스가 되지는 않기 때문에 모든 것이 GetOpenAPIClient에 달려 있어요.
Stripe 자체 설명이 각 메서드와 속성 위에 Pascal 주석으로 그대로 옮겨져요. 끄지 않는 한 그래요.
네 가지 모두 현재 사양으로 실제 생성을 돌려 본 결과예요.
약 110,000줄에 5.5 MB예요. 컴파일은 빠르지만 그 크기의 파일에서는 IDE 코드 편집기가 느려져요. -x는 "VERB endpoint" 형식으로 나열한 오퍼레이션을 빼고, 이어서 -p가 남은 오퍼레이션이 쓰지 않는 클래스를 제거해요. 열 수 있는 유닛과 열 수 없는 유닛의 차이가 여기서 갈려요.
하나같이 컴포지션에 관한 내용이에요. Stripe는 여러 곳에서 디스크리미네이터 매핑 없이 anyOf와 oneOf를 쓰기 때문에, 생성된 클래스는 분기마다 멤버 하나를 갖고 어느 쪽이 채워졌는지는 코드가 판단해요. 생성기는 조용히 하나를 고르는 대신 스키마별로 그 사실을 알려 줘요.
POST /v1/files는 문서에서 유일한 multipart/form-data 오퍼레이션인데, 생성된 PostFiles는 aExpand만 받아요. 필요하다면 TsgcHTTP1Client나 파일 업로드 API로 직접 올리세요.
Stripe는 API에 버전을 매기고 사양을 자주 고쳐요. 생성에 사용한 spec3.json을 고정해 프로젝트 옆에 두고, 재생성은 의도적으로 하세요. 생성기는 결정론적이라 같은 문서면 같은 유닛이 나와요.