Démarrage rapide de sgcOpenAPI

En un coup d'œil

Il n'y a aucun composant à déposer

C'est la seule chose à comprendre avant de commencer. sgcOpenAPI n'enregistre rien dans la palette de l'IDE et ne livre aucun package de conception. Le flux de travail est : générer, puis utiliser.

L'outil

sgcOpenAPI.exe, qui est à la fois un assistant graphique et une ligne de commande. Il lit une spécification et écrit un fichier .pas.

Ce qu'il écrit

Une unité contenant une classe cliente dérivée de TsgcOpenAPI_Client, une méthode par opération, les classes de requête et de réponse, et une fonction GetOpenAPIClient qui renvoie un singleton prêt à l'emploi.

Comment l'appeler

Ajoute l'unité générée à ton projet, place-la dans la clause uses, et appelle GetOpenAPIClient.YourOperation(...). Le résultat est un objet de réponse que tu libères quand tu en as fini avec lui.

Les packages

Cinq packages d'exécution sont livrés, contenant des SDK précompilés pour AWS, Azure, Google et Microsoft. Ils servent à compiler, pas à installer, car il n'y a pas de page de palette à ajouter.

Avant de commencer

Prérequis et éditions

La colonne d'édition indique le define qui conditionne le code, avec la ligne où il se trouve dans le propre Source/sgcVer.inc du produit.

Quoi	Valeur
IDE	Delphi 7 jusqu'à RAD Studio 13 pour le code généré. Les objets de réponse typés nécessitent XE7 ou ultérieur, et la démo livrée les protège avec `{$IF CompilerVersion >= 28.0}`. En dessous, la méthode générée renvoie une simple chaîne.
C++Builder	Non pris en charge pour le client généré. `SGC_HTTP_OPENAPI`, qui conditionne l'ensemble de `sgcHTTP_OpenAPI_Client.pas`, est défini dans un `{$IFNDEF BCB}` à la ligne 702 du `sgcVer.inc` du produit, donc une version C++Builder compile cette unité en rien.
Édition	Les versions de sgcOpenAPI sont figées sur les deux niveaux les plus bas. Les lignes 7 à 10 de son `sgcVer.inc` indiquent `{$IFDEF SGC_OPENAPI}` suivi de `{$UNDEF SGC_EDT_PRO}`, `{$UNDEF SGC_EDT_ENT}` et `{$UNDEF SGC_EDT_ALL}`, ce qui laisse Core et Standard définis. Les niveaux commerciaux dépendent du nombre de postes, pas des fonctionnalités.
Génération de serveur	La même version définit `SGC_HTTP_OPENAPI_SERVER` à la ligne 11, le générateur peut donc émettre un squelette de serveur en plus d'un client. Passe `-s` sur la ligne de commande.
Plateformes	Aucune garde de système d'exploitation au niveau de l'unité. Les seules conditions de l'unité de base du client généré sont l'import habituel `{$IFDEF MSWINDOWS}` et les substitutions de type d'identifiant de thread, donc Windows, macOS, Linux, Android et iOS compilent tous.
Activation de la licence	Si la machine n'a pas été activée, passe `-user` et `-password` sur la ligne de commande, sinon l'exécution se termine avec le code 2.

Le générateur accepte JSON et YAML, et lit les deux en local. Un document Swagger 2.0 est également converti en OpenAPI 3 en local. Le convertisseur distant est facultatif, via -r, et il envoie ta spécification à un serveur tiers, il reste donc désactivé sauf demande explicite.

Étape 1

Installer et générer

Il n'y a pas de package de conception à installer, l'installation est donc plus courte que pour les autres produits.

1. Décompresser

Décompresse le téléchargement dans un dossier, appelé {$DIR} ci-dessous. Tu obtiens Demos\, Bin\ et Source\.

2. Chemin de bibliothèque

Outils, Options, Bibliothèque. Ajoute {$DIR}\Source pour que les unités générées et la classe de base du client soient résolues. Il n'y a rien à installer dans l'IDE.

3. Facultatif, compiler un SDK précompilé

Si tu veux l'un des SDK fournis, ouvre le package d'exécution correspondant sous {$DIR}\Packages\ et compile-le. Ce sont des packages d'exécution, donc compile-les au lieu de les installer.

4. Générer un client

Lance Bin\sgcOpenAPI.exe pour l'assistant, ou utilise la ligne de commande. Une entrée, une sortie, et tu as une unité.

5. Ajouter l'unité à ton projet

Place le .pas généré à côté de tes autres unités, ajoute-le au projet et mets-le dans ta clause uses. C'est toute l'intégration.

QuickStart

Une spécification en entrée, un client opérationnel en sortie

Une ligne de commande génère l'unité. Un appel l'utilise. Le troisième onglet présente les options à connaître dès le premier jour.

ligne de commande

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

File successfully created geolocation.pas

Les deux options sont obligatoires. -i prend un fichier local ou une URL et accepte JSON et YAML, et -o est l'unité Pascal à écrire. Il existe un assistant graphique dans le même exécutable si tu préfères cliquer. Ajoute le .pas généré à ton projet et il est prêt à l'emploi.

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 est généré dans l'unité et ne prend aucun paramètre. Une méthode par opération, nommée d'après l'identifiant d'opération. L'objet de réponse est à toi de le libérer, c'est pourquoi la démo utilise un try finally. Sur les versions de Delphi antérieures à XE7, la méthode générée renvoie à la place une simple chaîne, et la démo livrée protège le chemin typé avec {$IF CompilerVersion >= 28.0}.

ligne de commande

-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

Sur une grande spécification, -x et -p ensemble font la différence entre une unité que tu peux ouvrir dans l'IDE et une que tu ne peux pas. -r existe aussi, et il est volontairement désactivé par défaut car il envoie toute la spécification à un convertisseur tiers.

La commande de génération est la ligne d'utilisation affichée par l'aide de l'outil lui-même. L'appel provient de la démo livrée Demos\20.Client\abstractapi.com\geolocation\fGeolocation.pas, avec les contrôles de la fiche remplacés par des littéraux. Cette démo livre la spécification et attend que tu génères l'unité, c'est pourquoi le démarrage rapide commence par le générateur.

Étape 2

Vérifier que le générateur a réussi

Deux choses à regarder, et l'une d'elles est scriptable.

Le message

L'outil affiche File successfully created suivi du chemin de sortie. Les erreurs vont toujours vers la sortie d'erreur standard, donc une exécution silencieuse qui n'a rien écrit n'est pas muette.

Le code de sortie

0 succès, 1 erreur, 2 licence invalide, 3 option invalide, 4 fichier de configuration invalide, 5 fichier d'entrée invalide, 6 fichier de sortie invalide, 7 la spécification n'a pas pu être convertie en document OpenAPI 3 valide. Teste-le dans ton script de compilation.

L'unité compile

Ajoute le .pas généré au projet et compile. Il doit compiler avec pour seule dépendance {$DIR}\Source dans le chemin de bibliothèque.

`IsSuccessful`

À l'exécution, l'objet de réponse te l'indique. Quand la valeur est false, ResponseError contient le message et ResponseCode le statut HTTP.

Problèmes courants

Ce qui se passe généralement mal la première fois

Six problèmes expliquent presque toutes les premières exécutions.

Tu cherches un composant dans la palette

Il n'y en a pas. sgcOpenAPI n'enregistre aucun composant et ne livre aucun package de conception. L'unité générée est le point d'intégration, et GetOpenAPIClient est le moyen d'atteindre le client.

L'unité nommée dans la démo n'existe pas

C'est normal. Les démos livrent la spécification et non l'unité générée, tu dois donc lancer d'abord le générateur. La démo de géolocalisation a besoin d'une unité nommée geolocation, qui sort de geolocation.json.

Code de sortie 2

La licence n'a pas été activée sur cette machine. Passe -user et -password sur la ligne de commande.

L'objet de réponse typé ne compile pas

Les réponses typées nécessitent XE7 ou ultérieur. La démo livrée les protège avec {$IF CompilerVersion >= 28.0} et se rabat sur une méthode qui renvoie une simple chaîne sur les compilateurs plus anciens. Conserve cette garde si tu prends en charge Delphi 7.

Rien ne compile sous C++Builder

SGC_HTTP_OPENAPI est défini dans un {$IFNDEF BCB} à la ligne 702 du sgcVer.inc du produit, donc la classe de base du client généré n'est pas du tout compilée pour C++Builder.

La spécification ne se convertit pas

Le code de sortie 7 signifie que le document n'a pas pu être transformé en document OpenAPI 3 valide. YAML et Swagger 2.0 sont gérés en local ; le convertisseur distant derrière -r est la solution de secours, et il envoie tout le fichier à un serveur qu'eSeGeCe ne contrôle pas.

Aller plus loin

Au-delà du premier client

Quatre directions, toutes issues du même générateur.

Générer un serveur, pas un client

Passe -s et le générateur émet un squelette de serveur à la place. Les démos de serveur montrent comment les opérations émises sont distribuées et validées par rapport à la spécification.

sgcOpenAPI Server

Utiliser les SDK précompilés

Plus d'un millier de spécifications sont déjà générées et livrées, dont AWS, Azure, Google et Microsoft. Compile le package voulu et saute complètement l'étape de génération.

Les API fournies

Réduire ce que tu génères

-x exclut des opérations par verbe et point d'accès, et -p élague les classes qu'aucune opération restante n'utilise. Sur une grande spécification, cela fait la différence entre une unité que tu peux ouvrir et une que tu ne peux pas.

Le parser

Brancher l'authentification

Le client généré porte une propriété Authentication, et -a choisit le schéma à la génération : aucun, basic, token, OAuth2 ou JWT.

Fonctionnalités de sgcOpenAPI

Ressources

Référence, démos et documentation

Les projets de démo sont livrés dans le téléchargement, sous Demos\ : des SDK précompilés, un client généré et deux exemples de serveur.

	Ce que fait sgcOpenAPI Le parser, le générateur et le composant serveur en une seule page.	Ouvrir
	Le parser Comment une spécification est lue, validée et transformée en types Pascal.	Ouvrir
	Le composant serveur Servir une API à partir d'une spécification plutôt que d'en consommer une.	Ouvrir
	API fournies Les SDK précompilés livrés prêts à compiler.	Ouvrir
	Télécharger l'essai Le générateur et les sources, limités dans le temps.	Ouvrir
	Qu'est-ce qu'OpenAPI Du contexte, si le format de spécification lui-même est nouveau pour toi.	Ouvrir

Lectures associées : générer un client Delphi à partir d'OpenAPI, regrouper les schémas, sgcOpenAPI comparé à swagger-codegen et le serveur OpenAPI. Chaque produit a son propre démarrage rapide, listé sur la page de prise en main.

FAQ

Questions sur le démarrage rapide de sgcOpenAPI

Aucun. sgcOpenAPI est un générateur de code et une bibliothèque d'exécution, et il n'enregistre rien dans la palette de l'IDE. Le produit ne contient aucun package de conception. Tu lances sgcOpenAPI.exe sur une spécification, il écrit une unité Pascal, et tu ajoutes cette unité à ton projet. À l'intérieur, GetOpenAPIClient renvoie un objet client prêt à l'emploi avec une méthode par opération.

L'outil l'affiche dans sa propre aide : sgcOpenAPI.exe -i "c:\openapi.json" -o "c:\openapi.pas". Les deux options sont obligatoires. -i prend un fichier local ou une URL, et JSON et YAML sont tous deux acceptés. -o est l'unité Pascal à écrire. Une valeur peut aussi être ajoutée après deux-points, comme dans -i:"c:\openapi.json".

De deux façons. L'outil affiche File successfully created suivi du chemin de sortie, et il définit un code de sortie que tu peux tester dans un script de compilation. Les codes sont 0 succès, 1 erreur, 2 licence invalide, 3 option invalide, 4 fichier de configuration invalide, 5 fichier d'entrée invalide, 6 fichier de sortie invalide, et 7 la spécification n'a pas pu être convertie en document OpenAPI 3 valide. Les erreurs vont toujours vers la sortie d'erreur standard.

La méthode générée renvoie un objet de réponse dérivé de TsgcOpenAPIResponse. Lis d'abord IsSuccessful. Quand la valeur est false, ResponseError contient le message et ResponseCode le statut HTTP. Libère l'objet de réponse quand tu en as fini avec lui, ce que fait la démo livrée dans un try finally.

Le client généré, non. SGC_HTTP_OPENAPI, qui entoure toute l'interface de sgcHTTP_OpenAPI_Client.pas, est défini dans un {$IFNDEF BCB} à la ligne 702 du sgcVer.inc du produit, donc sous C++Builder cette unité se compile en rien et le code généré n'a pas de classe de base. Génère pour Delphi.

Le code généré cible Delphi 7 et ultérieur. Les objets de réponse typés nécessitent XE7 ou ultérieur, et la démo livrée le rend explicite avec {$IF CompilerVersion >= 28.0} : au-dessus de cette ligne tu obtiens un objet de réponse avec des champs typés, en dessous la même méthode renvoie une simple chaîne. Conserve la garde si ton projet doit compiler sur les deux.

Oui. Passe -s et le générateur émet un squelette de serveur avec des attributs code-first au lieu d'un client. La version livrée sous le nom sgcOpenAPI définit SGC_HTTP_OPENAPI_SERVER à la ligne 11 de son sgcVer.inc, la partie serveur est donc présente dans chaque licence. Deux démos de serveur sont livrées sous Demos\30.Server.

Pas sauf si tu le demandes. Le YAML est lu en local, et un document Swagger 2.0 est converti en OpenAPI 3 en local. L'option -r, désactivée par défaut, autorise un repli vers le convertisseur public converter.swagger.io, et le texte d'aide dit clairement que cela envoie le fichier complet à un serveur qu'eSeGeCe ne contrôle pas. Laisse-la désactivée pour tout ce qui est confidentiel.

sgcOpenAPI en cinq minutes