openapi delphi generator

Gerador de clientes OpenAPI para Delphi

Gere SDKs do Delphi Client para qualquer API REST definida com a especificação OpenAPI.

Este gerador pode ler um documento OpenAPI (do arquivo local ou URL) de uma API REST e gerar classes Delphi que você pode usar para invocar esses pontos de extremidade da API REST de uma maneira amigável.

O gerador cria as classes DTO (representando as definições JSON usadas pela API) e as interfaces com os métodos que você pode chamar (representando os pontos de extremidade a serem invocados).

Uso

Faça o download dos binários e descompacte em uma pasta em seu disco. O gerador é um único arquivo exe de linha de comando chamado OpenApiDelphiGen.exe . Execute-o passando os parâmetros da linha de comando adequados. A ferramenta fornece um arquivo de ajuda mostrando todas as opções disponíveis.

Gerando o cliente

O exemplo a seguir gera arquivos do cliente para a popular API Swagger PetStore Exemplo.

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

O parâmetro -i indica o documento OpenAPI para importar. O parâmetro -o fornece a pasta de saída onde os arquivos Delphi devem ser gerados. O parâmetro -n é o nome da API, usada para prefixar os nomes da unidade e da classe. Finalmente, -m parâmetro indica como as classes e interfaces de serviço devem ser organizadas.

O gerador criará as seguintes unidades:

PetStoreClient é a unidade principal das classes e interfaces de serviço. PetStoreDTOs contém todas as classes DTO, e PetStoreJson possui código para serializar/deseralizar DTOs de e para o JSON.

Usando o cliente

Para usar o cliente, basta adicionar as unidades geradas às suas classes de uso. Instanciar o cliente e usar seus métodos. Observe que o código gerado depende das unidades fornecidas na pasta Dist, portanto, você também deve adicioná -las ao seu projeto.

Depois de instanciar o cliente, basta chamar um método de um serviço para invocar um terminal. O exemplo a seguir criará um novo animal de estimação no servidor, invocando o terminal 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 ;

Outro exemplo que recuperará e depois excluirá um animal de estimação:

  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);

Você deve criar e destruir todas as aulas do DTO. As classes e listas de propriedade das classes DTO são destruídas automaticamente.

Autenticação

Você pode definir a propriedade Config.AccessToken para autenticar com a API:

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

Ele definirá o cabeçalho HTTP Authorization com o valor do token prefixado pelo Bearer .

Compatibilidade do cliente

Atual O código gerado não requer nenhuma dependência das unidades de terceiros, trabalhando com uma instalação simples de Delphi. Atualmente, o código está usando a classe THttpClient do Unit System.Net.HttpClient para executar as solicitações HTTP, para que o cliente seja compilado apenas nas versões Delphi que fornecem essa classe.

Como alternativa, você pode forçar o cliente a usar componentes Indy para executar solicitações HTTP. Para isso, pode usar o seguinte snippet de código.

 uses { ... } , OpenApiRest, OpenApiIndy;

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

Você pode interceptar o momento em que um novo cliente TIdHTTP é criado - caso você queira configurar propriedades específicas como proxy ou manipuladores de IO. Para isso, você pode usar um 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 ;

Compilando e executando testes

Você pode compilar e executar o projeto de teste também sem dependências. Os testes foram criados usando Dunit para máxima compatibilidade com várias versões Delphi.

Compilando a ferramenta geradora

A própria ferramenta geradora usa bibliotecas de terceiros. Você não precisa deles para usá -lo, basta baixar o executável e usá -lo diretamente. Caso você queira compilar e depurar a ferramenta, você precisará das seguintes bibliotecas:

• VSoft.CommandLineParser
• TMS Biz

Observe que o TMS Biz é uma biblioteca comercial. Você pode usar a versão de teste para desenvolvimento (caso você queira contribuir com o projeto).

Licença

Este projeto é o código justo distribuído no Apache 2.0 com a Licença da Cláusula Commons .