openapi delphi generator

Generador de clientes de OpenApi para Delphi

Genere SDK del cliente Delphi para cualquier API REST definida con la especificación de OpenAPI.

Este generador puede leer un documento de OpenApi (desde el archivo local o la URL) de una API REST y generar clases de Delphi que puede usar para invocar tales puntos finales de API REST de manera amigable.

El generador crea las clases DTO (que representan las definiciones JSON utilizadas por la API) y las interfaces con los métodos que puede llamar (que representan los puntos finales para invocar).

Uso

Descargue los binarios y descomprima en una carpeta en su disco. El generador es un solo archivo EXE de línea de comandos llamado OpenApiDelphiGen.exe . Ejecutarlo pasando los parámetros de línea de comandos adecuados. La herramienta proporciona un archivo de ayuda que le muestra todas las opciones disponibles.

Generando el cliente

El siguiente ejemplo genera archivos de clientes para la popular API de ejemplo de Swagger PetStore.

OpenApiDelphiGen -i: " https://petstore.swagger.io/v2/swagger.json " -o: " C:PetStore " -n:PetStore -m:MultipleClientsFromFirstTagAndOperationId

El parámetro -i indica el documento OpenAPI para importar. El parámetro -o proporciona la carpeta de salida donde se deben generar los archivos Delphi. El parámetro -n es el nombre de la API, utilizado para prefijo los nombres de unidad y clase. Finalmente, el parámetro -m indica cómo se deben organizar las clases e interfaces de servicio.

El generador creará las siguientes unidades:

PetStoreClient es la unidad principal con las clases de servicio e interfaces. PetStoreDTOs contiene todas las clases de DTO, y PetStoreJson posee código para serializar/deserializar DTO desde y desde JSON.

Usando el cliente

Para usar el cliente, simplemente agregue las unidades generadas a sus clases de usos. Instanciar al cliente y utilizar sus métodos. Tenga en cuenta que el código generado depende de las unidades proporcionadas en la carpeta DIST, por lo que también debe agregarlas a su proyecto.

Una vez que esté instanciando al cliente, simplemente llame a un método de un servicio para invocar un punto final. El siguiente ejemplo creará una nueva mascota en el servidor invocando el punto final POST /Pets :

 uses { ... } , PetStoreClient, PetStoreDtos;

procedure TPetStoreClientTests.CreateAndGetPet ;
const
  PetId = 61341 ;
  CategoryId = 61341 ;
  TagId = 61341 ;
var
  Pet: TPet;
  Tag: TTag;
  Client: IPetStoreClient;
begin
  Client := TPetStoreClient.Create;

  // Create the pet
  Pet := TPet.Create;
  try
    Pet.Id := PetId;
    Pet. Name := ' Josephine ' ;
    Pet.Status := ' available ' ;

    Pet.Category := TCategory.Create;
    Pet.Category.Id := CategoryId;
    Pet.Category. Name := ' Terrier Dogs ' ;

    Pet.Tags := TTagList.Create;
    Tag := TTag.Create;
    Tag.Id := TagId;
    Tag. Name := ' Terrier ' ;
    Pet.Tags.Add(Tag);

    Pet.PhotoUrls.Add( ' http://dummy.com/dog.png ' );
    Client.Pet.AddPet(Pet);
  finally
    Pet.Free;
  end ;

Otro ejemplo que recuperará y luego eliminará una mascota:

  Client := TPetStoreClient.Create;
  Pet := Client.Pet.GetPetById(PetId);
  try
    Check(Pet <> nil , Format( ' Pet %d not found ' , [PetId]));
    CheckEquals(PetId, Pet.Id);
    CheckEquals( ' Josephine ' , Pet. Name );
    CheckEquals( ' available ' , Pet.Status);
  finally
    Pet.Free;
  end ;

  // Delete the newly created pet
  Client.Pet.DeletePet( ' special-key ' , PetId);

Debes crear y destruir todas las clases de DTO tú mismo. Las clases y listas propiedad de las clases DTO se destruyen automáticamente.

Autenticación

Puede establecer la propiedad Config.AccessToken para autenticar con la API:

Client.Config.AccessToken := ' <access token> ' ;

Establecerá el encabezado HTTP Authorization con el valor del token prefijado por Bearer .

Compatibilidad del cliente

Actual El código generado no requiere dependencia de las unidades de terceros, trabajando con una instalación simple de Delphi. Actualmente, el código está utilizando la clase THttpClient de Unit System.Net.HttpClient para realizar las solicitudes HTTP, por lo que el cliente solo se compilará en versiones de Delphi que proporcionan dicha clase.

Alternativamente, puede obligar al cliente a usar los componentes Indy para realizar solicitudes HTTP. Para eso, puede usar el siguiente fragmento de código.

 uses { ... } , OpenApiRest, OpenApiIndy;

begin
  // At the beginning of your application, set the DefaultRequestFactory
  DefaultRequestFactory := TIndyRestRequestFactory.Create;
end ;

Puede interceptar el momento en el que se crea un nuevo cliente TIdHTTP , en caso de que desee configurar propiedades específicas como Proxy o Panylers IO. Para eso puede usar un código como este:

 uses { ... } , OpenApiRest, OpenApiIndy, IdHTTP;

procedure TMainDataModule.IndyClientCreated (Client: TIdHTTP);
begin
  // Set extra Client properties here
end ;

procedure TMainDataModule.DataModuleCreate (Sender: TObject);
var
  Factory: TIndyRestRequestFactory;
begin
  // At the beginning of your application, set the DefaultRequestFactory
  Factory := TIndyRestRequestFactory.Create;
  DefaultRequestFactory := Factory;
  Factory.OnClientCreated := IndyClientCreated;
end ;

Compilación y ejecución de pruebas

Puede compilar y ejecutar el proyecto de prueba también sin dependencias. Las pruebas se crearon usando Dunit para la máxima compatibilidad con varias versiones de Delphi.

Compilación de la herramienta Generador

La herramienta Generator en sí utiliza bibliotecas de terceros. No necesita que lo usen, simplemente puede descargar el ejecutable y usarlo directamente. En caso de que desee compilar y depurar la herramienta, necesitará las siguientes bibliotecas:

• Vsoft.CommandLineParser
• TMS Biz

Tenga en cuenta que TMS Biz es una biblioteca comercial. Puede usar la versión de prueba para el desarrollo (en caso de que desee contribuir con el proyecto).

Licencia

Este proyecto es un código justo distribuido bajo Apache 2.0 con la licencia de la cláusula Commons .