Início rápido do sgcOpenAPI

Visão geral

Não há componente para soltar

Esta é a única coisa a entender antes de começar. O sgcOpenAPI não registra nada na paleta da IDE e não traz pacote de design-time. O fluxo é gerar e depois usar.

A ferramenta

sgcOpenAPI.exe, que é ao mesmo tempo um assistente gráfico e uma linha de comando. Ele lê uma especificação e escreve um arquivo .pas.

O que ele escreve

Uma unit contendo uma classe cliente derivada de TsgcOpenAPI_Client, um método por operação, as classes de requisição e de resposta e uma função GetOpenAPIClient que retorna um singleton pronto.

Como você o chama

Adicione a unit gerada ao seu projeto, coloque-a na cláusula uses e chame GetOpenAPIClient.YourOperation(...). O resultado é um objeto de resposta que você libera quando terminar de usá-lo.

Os pacotes

Acompanham cinco pacotes de runtime, com SDKs pré-compilados para AWS, Azure, Google e Microsoft. Eles são para compilar, não para instalar, porque não há página de paleta para adicionar.

Antes de começar

Requisitos e edições

A coluna de edição é o define que controla o código, com a linha em que ele aparece no Source/sgcVer.inc do próprio produto.

O quê	Valor
IDE	Do Delphi 7 ao RAD Studio 13 para o código gerado. Os objetos de resposta tipados exigem XE7 ou posterior, e o demo que acompanha o pacote os protege com `{$IF CompilerVersion >= 28.0}`. Abaixo disso, o método gerado retorna uma string simples.
C++Builder	Sem suporte para o cliente gerado. `SGC_HTTP_OPENAPI`, que controla todo o `sgcHTTP_OpenAPI_Client.pas`, é definido dentro de um `{$IFNDEF BCB}` na linha 702 do `sgcVer.inc` do produto, então uma compilação C++Builder compila essa unit como nada.
Edição	As compilações do sgcOpenAPI são fixadas nos dois níveis mais baixos. As linhas 7 a 10 de seu `sgcVer.inc` dizem `{$IFDEF SGC_OPENAPI}` seguido de `{$UNDEF SGC_EDT_PRO}`, `{$UNDEF SGC_EDT_ENT}` e `{$UNDEF SGC_EDT_ALL}`, deixando Core e Standard definidos. Os níveis comerciais são por número de licenças, não por recurso.
Geração de servidor	A mesma compilação define `SGC_HTTP_OPENAPI_SERVER` na linha 11, então o gerador pode emitir um stub de servidor além de um cliente. Passe `-s` na linha de comando.
Plataformas	Nenhuma restrição de sistema operacional no escopo da unit. As únicas condicionais dentro da unit base do cliente gerado são o habitual import `{$IFDEF MSWINDOWS}` e as trocas de tipo de id de thread, então Windows, macOS, Linux, Android e iOS compilam.
Ativação da licença	Se a máquina não foi ativada, passe `-user` e `-password` na linha de comando, caso contrário a execução termina com o código 2.

O gerador aceita JSON e YAML e lê ambos localmente. Um documento Swagger 2.0 também é convertido localmente para OpenAPI 3. O conversor remoto é opcional, por meio de -r, e envia sua especificação a um servidor de terceiros, então permanece desligado a menos que você peça.

Passo 1

Instale e gere

Não há pacote de design-time para instalar, então a instalação é mais curta do que a dos outros produtos.

1. Descompacte

Descompacte o download em uma pasta, chamada de {$DIR} abaixo. Você obtém Demos\, Bin\ e Source\.

2. Caminho da biblioteca

Tools, Options, Library. Adicione {$DIR}\Source para que as units geradas e a classe base do cliente sejam resolvidas. Não há nada para instalar na IDE.

3. Opcional, compile um SDK pré-compilado

Se você quer um dos SDKs incluídos, abra o pacote de runtime correspondente em {$DIR}\Packages\ e compile-o. São pacotes de runtime, então compile em vez de instalar.

4. Gere um cliente

Execute Bin\sgcOpenAPI.exe para o assistente ou use a linha de comando. Uma entrada, uma saída e você tem uma unit.

5. Adicione a unit ao seu projeto

Coloque o .pas gerado ao lado das suas outras units, adicione-o ao projeto e coloque-o na cláusula uses. Essa é toda a integração.

QuickStart

Especificação entra, cliente funcional sai

Uma linha de comando gera a unit. Uma chamada a usa. A terceira aba mostra as opções que vale conhecer no primeiro dia.

command line

> sgcOpenAPI.exe -i "geolocation.json" -o "geolocation.pas"

File successfully created geolocation.pas

As duas opções são obrigatórias. -i recebe um arquivo local ou uma URL e aceita JSON e YAML, e -o é a unit Pascal a escrever. Há um assistente gráfico no mesmo executável, se você preferir clicar. Adicione o .pas gerado ao seu projeto e ele está pronto para uso.

fGeolocation.pas

uses
  geolocation;   // the unit you just generated

procedure TfrmGeolocation.btnGeolocationClick(Sender: TObject);
var
  oResponse: TsgcOpenAPI_Retrieve_the_location_of_an_IP_address_Response;
begin
  oResponse := GetOpenAPIClient.Retrieve_the_location_of_an_IP_address(
    txtAPIKey.Text, txtIPAddress.Text);
  try
    if oResponse.IsSuccessful then
      memoResponse.Lines.Text :=
        'country: ' + oResponse.Successful.Country + #13#10 +
        'city: ' + oResponse.Successful.City
    else
      memoResponse.Lines.Text := oResponse.ResponseError;
  finally
    oResponse.Free;
  end;
end;

GetOpenAPIClient é gerado dentro da unit e não recebe parâmetros. Um método por operação, nomeado a partir do id da operação. O objeto de resposta é seu para liberar, e é por isso que o demo usa um try finally. Em versões do Delphi anteriores ao XE7, o método gerado retorna uma string simples, e o demo que acompanha o pacote protege o caminho tipado com {$IF CompilerVersion >= 28.0}.

command line

-s              generate a server stub instead of a client
-a 3            add an OAuth2 flow to the generated client
                (0 none, 1 basic, 2 token, 3 oauth2, 4 jwt)
-u <url>        set the base url the generated client uses
-m 1            name methods from summary rather than operationid
                (0 operationid, 1 summary, 2 endpoint)
-x <list|file>  exclude operations, as "VERB endpoint"
-p              generate only the classes the kept operations use
-nc             do not create pascal classes
-l              show progress messages (errors are always shown)
-user -password activate the licence on this machine

Em uma especificação grande, -x e -p juntos fazem a diferença entre uma unit que você consegue abrir na IDE e uma que não consegue. -r também existe, e fica desligado por padrão de propósito, porque envia a especificação inteira a um conversor de terceiros.

O comando de geração é a linha de uso impressa pela própria ajuda da ferramenta. A chamada é o demo que acompanha o pacote, Demos\20.Client\abstractapi.com\geolocation\fGeolocation.pas, com os controles do formulário substituídos por literais. Esse demo traz a especificação e espera que você gere a unit, e é por isso que o início rápido começa pelo gerador.

Passo 2

Confira se o gerador teve sucesso

Duas coisas para olhar, e uma delas pode ser automatizada por script.

A mensagem

A ferramenta imprime File successfully created seguido do caminho de saída. Os erros sempre vão para a saída de erro padrão, então uma execução silenciosa que não escreveu nada não é muda.

O código de saída

0 sucesso, 1 erro, 2 licença inválida, 3 opção inválida, 4 arquivo de configuração inválido, 5 arquivo de entrada inválido, 6 arquivo de saída inválido, 7 a especificação não pôde ser convertida em um documento OpenAPI 3 válido. Teste-o no seu script de build.

A unit compila

Adicione o .pas gerado ao projeto e compile. Ele deve compilar usando apenas {$DIR}\Source no caminho da biblioteca.

`IsSuccessful`

Em tempo de execução, o objeto de resposta informa. Quando é false, ResponseError traz a mensagem e ResponseCode o status HTTP.

Problemas comuns

O que costuma dar errado na primeira vez

Seis problemas respondem por quase toda primeira execução.

Você está procurando um componente na paleta

Não há nenhum. O sgcOpenAPI não registra componentes e não traz pacote de design-time. A unit gerada é o ponto de integração, e GetOpenAPIClient é como você alcança o cliente.

A unit citada no demo não existe

Isso é esperado. Os demos trazem a especificação e não a unit gerada, então você executa primeiro o gerador. O demo de geolocalização precisa de uma unit chamada geolocation, que sai de geolocation.json.

Código de saída 2

A licença não foi ativada nesta máquina. Passe -user e -password na linha de comando.

O objeto de resposta tipado não compila

As respostas tipadas exigem XE7 ou posterior. O demo que acompanha o pacote as protege com {$IF CompilerVersion >= 28.0} e recorre a um método que retorna uma string simples em compiladores mais antigos. Mantenha essa proteção se você oferece suporte ao Delphi 7.

Nada compila no C++Builder

SGC_HTTP_OPENAPI é definido dentro de um {$IFNDEF BCB} na linha 702 do sgcVer.inc do produto, então a classe base do cliente gerado não é compilada de forma alguma para o C++Builder.

A especificação não é convertida

O código de saída 7 significa que o documento não pôde ser transformado em um documento OpenAPI 3 válido. YAML e Swagger 2.0 são tratados localmente; o conversor remoto por trás de -r é a saída de emergência, e ele envia o arquivo inteiro a um servidor que a eSeGeCe não controla.

Aprofunde-se

Além do primeiro cliente

Quatro direções, todas a partir do mesmo gerador.

Gere um servidor, não um cliente

Passe -s e o gerador emite um stub de servidor. Os demos de servidor mostram como as operações emitidas são despachadas e validadas contra a especificação.

sgcOpenAPI Server

Use os SDKs pré-compilados

Mais de mil especificações já estão geradas e incluídas, entre elas AWS, Azure, Google e Microsoft. Compile o pacote que quiser e pule totalmente a etapa de geração.

As APIs incluídas

Reduza o que você gera

-x exclui operações por verbo e endpoint, e -p remove as classes que nenhuma operação restante usa. Em uma especificação grande, isso faz a diferença entre uma unit que você consegue abrir e uma que não consegue.

O parser

Conecte a autenticação

O cliente gerado traz uma propriedade Authentication, e -a escolhe o esquema na hora da geração: nenhum, basic, token, OAuth2 ou JWT.

Recursos do sgcOpenAPI

Recursos

Referência, demos e documentação

Os projetos de demo acompanham o download, em Demos\: SDKs pré-compilados, um cliente gerado e dois exemplos de servidor.

	O que o sgcOpenAPI faz O parser, o gerador e o componente servidor em uma só página.	Abrir
	O parser Como uma especificação é lida, validada e transformada em tipos Pascal.	Abrir
	O componente servidor Servir uma API a partir de uma especificação em vez de consumi-la.	Abrir
	APIs incluídas Os SDKs pré-compilados que acompanham o pacote, prontos para compilar.	Abrir
	Baixe a versão de avaliação O gerador e o código-fonte, com tempo limitado.	Abrir
	O que é OpenAPI Contexto, se o próprio formato de especificação for novidade para você.	Abrir

Leitura relacionada: gerando um cliente Delphi a partir do OpenAPI, empacotando schemas, o sgcOpenAPI comparado com o swagger-codegen e o servidor OpenAPI. Cada produto tem seu próprio início rápido, listado na página de primeiros passos.

FAQ

Perguntas sobre o início rápido do sgcOpenAPI

Nenhum. O sgcOpenAPI é um gerador de código e uma biblioteca de runtime, e não registra nada na paleta da IDE. Não há nenhum pacote de design-time no produto. Você executa sgcOpenAPI.exe contra uma especificação, ele escreve uma unit Pascal e você adiciona essa unit ao seu projeto. Dentro dela, GetOpenAPIClient retorna um objeto cliente pronto, com um método por operação.

A ferramenta a imprime em sua própria ajuda: sgcOpenAPI.exe -i "c:\openapi.json" -o "c:\openapi.pas". As duas opções são obrigatórias. -i recebe um arquivo local ou uma URL, e JSON e YAML são ambos aceitos. -o é a unit Pascal a escrever. Um valor também pode ser anexado após dois-pontos, como em -i:"c:\openapi.json".

De duas formas. A ferramenta imprime File successfully created seguido do caminho de saída e define um código de saída que você pode testar em um script de build. Os códigos são 0 sucesso, 1 erro, 2 licença inválida, 3 opção inválida, 4 arquivo de configuração inválido, 5 arquivo de entrada inválido, 6 arquivo de saída inválido e 7 a especificação não pôde ser convertida em um documento OpenAPI 3 válido. Os erros sempre vão para a saída de erro padrão.

O método gerado retorna um objeto de resposta derivado de TsgcOpenAPIResponse. Leia primeiro IsSuccessful. Quando é false, ResponseError traz a mensagem e ResponseCode o status HTTP. Libere o objeto de resposta quando terminar de usá-lo, o que o demo que acompanha o pacote faz em um try finally.

O cliente gerado não. SGC_HTTP_OPENAPI, que envolve toda a interface de sgcHTTP_OpenAPI_Client.pas, é definido dentro de um {$IFNDEF BCB} na linha 702 do sgcVer.inc do produto, então no C++Builder essa unit compila como nada e o código gerado fica sem classe base. Gere para o Delphi.

O código gerado tem como alvo o Delphi 7 e posteriores. Os objetos de resposta tipados exigem XE7 ou posterior, e o demo que acompanha o pacote deixa isso explícito com {$IF CompilerVersion >= 28.0}: acima da linha você obtém um objeto de resposta com campos tipados, abaixo dela o mesmo método retorna uma string simples. Mantenha a proteção se o seu projeto precisa compilar nos dois.

Sim. Passe -s e o gerador emite um stub de servidor com atributos code-first em vez de um cliente. A compilação que acompanha o sgcOpenAPI define SGC_HTTP_OPENAPI_SERVER na linha 11 de seu sgcVer.inc, então o lado do servidor está presente em todas as licenças. Dois demos de servidor acompanham o pacote em Demos\30.Server.

Não, a menos que você peça. O YAML é lido localmente, e um documento Swagger 2.0 é convertido para OpenAPI 3 localmente. A opção -r, desligada por padrão, permite recorrer ao conversor público em converter.swagger.io, e o texto de ajuda diz claramente que isso envia o arquivo completo a um servidor que a eSeGeCe não controla. Deixe-a desligada para qualquer coisa confidencial.

sgcOpenAPI em cinco minutos