Stripe publica y mantiene una descripción OpenAPI 3 oficial de su API. sgcOpenAPI no incluye un componente de Stripe escrito a mano, incluye un generador. Ejecutas sgcOpenAPI.exe una vez sobre esa especificación y obtienes una sola unit Pascal con un método por operación, una clase de respuesta tipada para cada uno de ellos y una función GetOpenAPIClient que te entrega un cliente listo para usar.
Las cifras que siguen se midieron ejecutando el generador sobre el spec3.json actual y compilando el resultado, no son estimaciones.
openapi/spec3.json en github.com/stripe/openapi, declarada como OpenAPI 3.0.0. No hace falta ningún paso de conversión.
419 paths se convierten en 594 métodos y 594 clases de respuesta, junto a 1.747 clases de modelo, en una sola unit de unas 110.000 líneas.
Genera con -a 2 y asigna Authentication.Token.BearerToken en tiempo de ejecución. El cliente envía entonces Authorization: Bearer en cada petición.
La unit generada compila limpia en RAD Studio 12 para Win32 sin nada en la ruta de librerías salvo la carpeta Source de sgcOpenAPI.
Descarga el spec3.json del repositorio público de Stripe, o pasa la URL directamente a -i. Las dos opciones son obligatorias, todo lo demás tiene un valor por defecto.
> sgcOpenAPI.exe -i "spec3.json" -o "stripe.pas" -a 2 File successfully created stripe.pas
-i acepta un archivo local o una URL, en JSON o en YAML. -o es la unit Pascal que se escribe, y la unit toma el nombre de ese archivo. -a 2 selecciona la autenticación por token, que es lo que necesita la clave secreta de Stripe. El mismo ejecutable es además un asistente gráfico cuando lo arrancas sin parámetros. La ejecución termina con código de salida 0 si todo va bien, y un script de compilación puede comprobar el 5 (archivo de entrada), el 6 (archivo de salida) o el 7 (el documento no se pudo convertir en un documento OpenAPI 3 válido).
Añade el .pas generado a tu proyecto, ponlo en una cláusula uses, y esa es toda la integración. No hay ningún componente que instalar, porque sgcOpenAPI no registra ninguno y no incluye paquete de diseño.
Asigna la clave secreta una vez en el cliente y llama al método que el generador ha nombrado a partir del operation id. Los operation ids de Stripe ya son identificadores Pascal válidos, así que PostCharges es exactamente lo que obtienes.
uses stripe; // la unit que acabas de generar 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 no recibe parámetros y devuelve un cliente que no tienes que liberar. La URL base sale de la entrada servers de la especificación, así que el constructor generado ya establece https://api.stripe.com/ y solo la sobrescribes con -u al generar o con SetBaseURL en tiempo de ejecución. El objeto de respuesta sí es tuyo, y por eso el ejemplo usa un try finally. IsSuccessful es cierto para los estados 200 a 299, y ResponseCode y ResponseError llevan el resto.
Esto es lo único de Stripe que sorprende a la gente, y viene de la especificación, no del generador.
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;
Los 593 cuerpos de petición de la especificación de Stripe están declarados como application/x-www-form-urlencoded, así que el parámetro generado es const aBody: string y el formulario lo construyes tú, con la notación de corchetes propia de Stripe. Las respuestas son otra historia: están declaradas con esquemas con nombre, así que cada una se convierte en una clase que lees a través de propiedades.
La unit refleja el documento. No hay nada seleccionado a mano, así que todo lo que Stripe describe está presente y todo lo que Stripe omite no lo está.
594 en total, nombrados a partir del operation id quitando cualquier carácter que no pueda aparecer en un identificador Pascal. -m 1 los nombra a partir del summary, y -m 2 a partir del endpoint.
TsgcOpenAPI_PostCharges_Response desciende de TsgcOpenAPIResponse, lleva Successful más una propiedad por cada estado de error declarado, y hereda IsSuccessful, ResponseCode y ResponseError.
Todos los esquemas que declara Stripe, incluido el objeto error compartido, los objetos charge, customer, invoice y subscription, y los payloads de eventos.
Los parámetros de query opcionales se convierten en argumentos con valor por defecto, en orden de declaración, así que GetCharges recibe aCreated, aCustomer, aEnding_before, aExpand, aLimit y los demás sin que toques ninguna URL.
Los tags del documento se emiten como comentarios que agrupan los métodos dentro de la única clase. No se convierten en clases separadas, así que todo cuelga de GetOpenAPIClient.
Las descripciones propias de Stripe se trasladan como comentarios Pascal encima de cada método y cada propiedad, salvo que las desactives.
Las cuatro salieron de una ejecución real del generador sobre la especificación actual.
Unas 110.000 líneas y 5,5 MB. Compila rápido, pero el editor de código del IDE va lento con un archivo de ese tamaño. -x descarta las operaciones que listes como "VERB endpoint" y -p elimina después las clases que ya no usa ninguna operación, que es la diferencia entre una unit que puedes abrir y una que no.
Todos hablan de composición. Stripe usa anyOf y oneOf sin mapeo de discriminador en muchos sitios, así que la clase generada lleva un miembro por rama y es tu código el que decide cuál se ha rellenado. El generador lo indica esquema por esquema en lugar de elegir en silencio.
POST /v1/files es la única operación multipart/form-data del documento, y el PostFiles generado solo recibe aExpand. Si lo necesitas, sube el archivo con TsgcHTTP1Client o directamente contra la API de subida de archivos.
Stripe versiona su API y revisa la especificación a menudo. Fija el spec3.json desde el que generaste, guárdalo junto a tu proyecto y regenera de forma deliberada. El generador es determinista, así que el mismo documento da la misma unit.
Cómo el lector maneja especificaciones reales, incluidas las palabras clave de composición que producen la mayoría de los avisos de Stripe.
Leer post →Especificaciones multi-archivo y punteros $ref externos, que se incorporan antes de leer el documento.
Notas de la versión actual, con las opciones del generador y los cambios del lector.
Leer post →