A Stripe publica e mantém uma descrição OpenAPI 3 oficial da sua API. O sgcOpenAPI não entrega um componente Stripe escrito à mão, ele entrega um gerador. Você roda o sgcOpenAPI.exe uma vez sobre essa especificação e obtém uma única unit Pascal com um método por operação, uma classe de resposta tipada para cada um deles e uma função GetOpenAPIClient que devolve um cliente pronto.
Os números abaixo foram medidos rodando o gerador sobre o spec3.json atual e compilando o resultado, não foram estimados.
openapi/spec3.json em github.com/stripe/openapi, declarado como OpenAPI 3.0.0. Nenhuma etapa de conversão é necessária.
419 paths viram 594 métodos e 594 classes de resposta, junto com 1.747 classes de modelo, em uma única unit de cerca de 110.000 linhas.
Gere com -a 2 e defina Authentication.Token.BearerToken em tempo de execução. O cliente passa a enviar Authorization: Bearer em toda requisição.
A unit gerada compila limpa no RAD Studio 12 para Win32 sem nada no library path além da pasta Source do sgcOpenAPI.
Baixe o spec3.json do repositório público da Stripe, ou passe a URL bruta direto para -i. Os dois switches são obrigatórios, todo o resto tem um valor padrão.
> sgcOpenAPI.exe -i "spec3.json" -o "stripe.pas" -a 2 File successfully created stripe.pas
-i aceita um arquivo local ou uma URL, em JSON e em YAML. -o é a unit Pascal a gravar, e a unit recebe o nome desse arquivo. -a 2 seleciona a autenticação por token, que é o que a secret key da Stripe precisa. O mesmo executável também é um assistente gráfico quando você o inicia sem parâmetros. A execução termina com código de saída 0 em caso de sucesso, e um script de build pode testar 5 (arquivo de entrada), 6 (arquivo de saída) ou 7 (o documento não pôde ser transformado em um documento OpenAPI 3 válido).
Adicione o .pas gerado ao seu projeto, coloque-o em uma cláusula uses, e essa é toda a integração. Não há componente para instalar, porque o sgcOpenAPI não registra nenhum e não entrega pacote de design-time.
Defina a secret key uma vez no cliente e depois chame o método que o gerador nomeou a partir do operation id. Os operation ids da Stripe já são identificadores Pascal válidos, então PostCharges é exatamente o que você obtém.
uses stripe; // a unit que você acabou de gerar 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;
O GetOpenAPIClient não recebe parâmetros e devolve um cliente que você não libera. A URL base sai da entrada servers da especificação, então o construtor gerado já define https://api.stripe.com/ e você só a sobrescreve com -u na geração ou com SetBaseURL em tempo de execução. O objeto de resposta é seu, e por isso o exemplo usa um try finally. O IsSuccessful é verdadeiro para os status 200 a 299, e ResponseCode e ResponseError carregam o resto.
Essa é a única coisa da Stripe que surpreende as pessoas, e vem da especificação, não do gerador.
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;
Cada um dos 593 corpos de requisição da especificação da Stripe é declarado como application/x-www-form-urlencoded, então o parâmetro gerado é const aBody: string e você monta o formulário por conta própria, na notação de colchetes da própria Stripe. As respostas são outra história: são declaradas com schemas nomeados, então cada uma vira uma classe que você lê por propriedades.
A unit espelha o documento. Nada é curado, então tudo o que a Stripe descreve está presente e tudo o que a Stripe deixa de fora não está.
594 deles, nomeados a partir do operation id, com qualquer caractere que não possa aparecer em um identificador Pascal removido. Com -m 1 eles são nomeados a partir do summary, e com -m 2 a partir do endpoint.
A TsgcOpenAPI_PostCharges_Response descende de TsgcOpenAPIResponse, carrega Successful mais uma propriedade por status de erro declarado, e herda IsSuccessful, ResponseCode e ResponseError.
Cada schema que a Stripe declara, incluindo o objeto error compartilhado, os objetos charge, customer, invoice e subscription, e os payloads de eventos.
Parâmetros de query opcionais viram argumentos com valor padrão, na ordem de declaração, então o GetCharges recebe aCreated, aCustomer, aEnding_before, aExpand, aLimit e os demais sem que você toque em uma URL.
As tags do documento são emitidas como comentários que agrupam os métodos dentro da classe única. Elas não viram classes separadas, então tudo pende do GetOpenAPIClient.
As descrições da própria Stripe são levadas adiante como comentários Pascal acima de cada método e de cada propriedade, a menos que você as desligue.
As quatro saíram de uma geração real sobre a especificação atual.
Cerca de 110.000 linhas e 5,5 MB. Ela compila rápido, mas o editor de código da IDE fica lento com um arquivo desse tamanho. O -x descarta as operações que você lista como "VERB endpoint" e o -p em seguida remove as classes que nenhuma operação restante usa, o que faz a diferença entre uma unit que você consegue abrir e uma que não.
Todos eles são sobre composição. A Stripe usa anyOf e oneOf sem um mapeamento de discriminator em muitos lugares, então a classe gerada carrega um membro por ramo e o seu código decide qual deles foi preenchido. O gerador avisa por schema em vez de escolher em silêncio.
O POST /v1/files é a única operação multipart/form-data do documento, e o PostFiles gerado recebe apenas aExpand. Faça o upload pelo TsgcHTTP1Client ou diretamente pela API de upload de arquivos, se precisar dele.
A Stripe versiona a sua API e revisa a especificação com frequência. Fixe o spec3.json a partir do qual você gerou, mantenha-o junto do projeto e regenere de forma deliberada. O gerador é determinístico, então o mesmo documento dá a mesma unit.
Como o leitor lida com especificações reais, incluindo as palavras-chave de composição que produzem a maior parte dos avisos da Stripe.
Leia o post →Especificações multiarquivo e ponteiros $ref externos, que são incorporados antes de o documento ser lido.
Release notes da versão atual, com as opções do gerador e as mudanças do leitor.
Leia o post →