sgcOpenAPI snelstart

In één oogopslag

Er is geen component om te plaatsen

Dit is het ene wat je moet begrijpen voordat je begint. sgcOpenAPI registreert niets op het IDE-palet en levert geen designtime-package mee. De werkwijze is: eerst genereren, dan gebruiken.

De tool

sgcOpenAPI.exe, dat zowel een GUI-wizard als een opdrachtregel is. Het leest een specificatie en schrijft één .pas-bestand.

Wat het schrijft

Een unit met een clientklasse afgeleid van TsgcOpenAPI_Client, één methode per operatie, de verzoek- en responsklassen en een functie GetOpenAPIClient die een kant-en-klare singleton teruggeeft.

Hoe je het aanroept

Voeg de gegenereerde unit toe aan je project, zet die in de uses-clausule en roep GetOpenAPIClient.YourOperation(...) aan. Het resultaat is een responsobject dat je vrijgeeft zodra je ermee klaar bent.

De packages

Er worden vijf runtime-packages meegeleverd met kant-en-klare SDK's voor AWS, Azure, Google en Microsoft. Ze zijn om te compileren, niet om te installeren, omdat er geen palettabpagina is om toe te voegen.

Voordat je begint

Vereisten en edities

De editiekolom noemt de define die de code afschermt, met het regelnummer in de eigen Source/sgcVer.inc van het product.

Onderdeel	Waarde
IDE	Delphi 7 tot en met RAD Studio 13 voor de gegenereerde code. Getypeerde responsobjecten vereisen XE7 of hoger en de meegeleverde demo beveiligt ze met `{$IF CompilerVersion >= 28.0}`. Daaronder geeft de gegenereerde methode een gewone string terug.
C++Builder	Niet ondersteund voor de gegenereerde client. `SGC_HTTP_OPENAPI`, dat het geheel van `sgcHTTP_OpenAPI_Client.pas` afschermt, wordt gedefinieerd binnen een `{$IFNDEF BCB}` op regel 702 van de `sgcVer.inc` van het product, dus een C++Builder-build compileert die unit tot niets.
Editie	sgcOpenAPI-builds zijn vastgezet op de twee laagste niveaus. Regel 7 tot 10 van de `sgcVer.inc` luiden `{$IFDEF SGC_OPENAPI}` gevolgd door `{$UNDEF SGC_EDT_PRO}`, `{$UNDEF SGC_EDT_ENT}` en `{$UNDEF SGC_EDT_ALL}`, waardoor Core en Standard gedefinieerd blijven. De commerciële niveaus zijn gebaseerd op het aantal gebruikers, niet op functies.
Servergeneratie	Dezelfde build definieert `SGC_HTTP_OPENAPI_SERVER` op regel 11, dus de generator kan zowel een serverstub als een client uitvoeren. Geef `-s` mee op de opdrachtregel.
Platforms	Geen besturingssysteembeveiliging op unitniveau. De enige voorwaarden in de basisunit van de gegenereerde client zijn de gebruikelijke `{$IFDEF MSWINDOWS}`-import en wissels van het thread-id-type, dus Windows, macOS, Linux, Android en iOS compileren allemaal.
Licentieactivering	Als de machine niet is geactiveerd, geef dan `-user` en `-password` mee aan de opdrachtregel, anders eindigt de run met code 2.

De generator accepteert JSON en YAML en leest beide lokaal. Een Swagger 2.0-document wordt ook lokaal omgezet naar OpenAPI 3. De externe converter is opt-in, via -r, en uploadt je specificatie naar een server van een derde partij, dus die blijft uit tenzij je erom vraagt.

Stap 1

Installeren en genereren

Er is geen designtime-package om te installeren, dus de installatie is korter dan bij de andere producten.

1. Uitpakken

Pak de download uit in een map, hieronder {$DIR} genoemd. Je krijgt Demos\, Bin\ en Source\.

2. Bibliotheekpad

Tools, Options, Library. Voeg {$DIR}\Source toe zodat de gegenereerde units en de basisklasse van de client worden gevonden. Er hoeft niets in de IDE te worden geïnstalleerd.

3. Optioneel: een kant-en-klare SDK compileren

Als je een van de meegeleverde SDK's wilt, open dan het bijbehorende runtime-package onder {$DIR}\Packages\ en compileer het. Dit zijn runtime-packages, dus compileren in plaats van installeren.

4. Een client genereren

Voer Bin\sgcOpenAPI.exe uit voor de wizard, of gebruik de opdrachtregel. Eén invoer, één uitvoer en je hebt een unit.

5. De unit aan je project toevoegen

Zet de gegenereerde .pas naast je andere units, voeg die toe aan het project en zet die in je uses-clausule. Dat is de hele integratie.

QuickStart

Specificatie erin, werkende client eruit

Eén opdrachtregel genereert de unit. Eén aanroep gebruikt die. Het derde tabblad toont de schakelaars die je op de eerste dag moet kennen.

command line

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

File successfully created geolocation.pas

Beide schakelaars zijn verplicht. -i neemt een lokaal bestand of een URL en accepteert JSON en YAML, en -o is de Pascal-unit die wordt geschreven. In hetzelfde uitvoerbare bestand zit een GUI-wizard als je liever klikt. Voeg de gegenereerde .pas toe aan je project en het is klaar voor gebruik.

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 wordt in de unit gegenereerd en heeft geen parameters. Eén methode per operatie, vernoemd naar de operatie-id. Het responsobject moet je zelf vrijgeven, en daarom gebruikt de demo een try finally. Op Delphi-versies vóór XE7 geeft de gegenereerde methode in plaats daarvan een gewone string terug en de meegeleverde demo beveiligt het getypeerde pad met {$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

Bij een grote specificatie is -x samen met -p het verschil tussen een unit die je in de IDE kunt openen en een die je niet kunt openen. -r bestaat ook en staat bewust standaard uit, omdat het de hele specificatie uploadt naar een converter van een derde partij.

De genereeropdracht is de gebruiksregel die de eigen help van de tool afdrukt. De aanroep is de meegeleverde demo Demos\20.Client\abstractapi.com\geolocation\fGeolocation.pas, met de formulierbesturingselementen vervangen door literals. Die demo levert de specificatie mee en verwacht dat je de unit zelf genereert, en daarom begint de snelstart met de generator.

Stap 2

Controleer of de generator is geslaagd

Twee dingen om te bekijken, en een daarvan is te scripten.

De melding

De tool drukt File successfully created af, gevolgd door het uitvoerpad. Fouten gaan altijd naar standard error, dus een stille run die niets heeft geschreven, is niet echt stil.

De exitcode

0 geslaagd, 1 fout, 2 ongeldige licentie, 3 ongeldige schakelaar, 4 ongeldig configuratiebestand, 5 ongeldig invoerbestand, 6 ongeldig uitvoerbestand, 7 de specificatie kon niet worden omgezet naar een geldig OpenAPI 3-document. Test die in je buildscript.

De unit compileert

Voeg de gegenereerde .pas toe aan het project en bouw. Het moet compileren met niets anders dan {$DIR}\Source in het bibliotheekpad.

`IsSuccessful`

Tijdens runtime vertelt het responsobject het je. Als de waarde false is, bevat ResponseError de melding en ResponseCode de HTTP-status.

Veelvoorkomende problemen

Wat er de eerste keer meestal misgaat

Zes problemen verklaren bijna elke eerste run.

Je zoekt een component op het palet

Dat is er niet. sgcOpenAPI registreert geen componenten en levert geen designtime-package mee. De gegenereerde unit is het integratiepunt en met GetOpenAPIClient bereik je de client.

De unit die in de demo wordt genoemd, bestaat niet

Dat is normaal. De demo's leveren de specificatie mee en niet de gegenereerde unit, dus je voert eerst de generator uit. De geolocatiedemo heeft een unit met de naam geolocation nodig, die uit geolocation.json komt.

Exitcode 2

De licentie is niet geactiveerd op deze machine. Geef -user en -password mee op de opdrachtregel.

Het getypeerde responsobject compileert niet

Getypeerde responses vereisen XE7 of hoger. De meegeleverde demo beveiligt ze met {$IF CompilerVersion >= 28.0} en valt op oudere compilers terug op een methode die een gewone string teruggeeft. Behoud die beveiliging als je Delphi 7 ondersteunt.

Niets compileert onder C++Builder

SGC_HTTP_OPENAPI wordt gedefinieerd binnen een {$IFNDEF BCB} op regel 702 van de sgcVer.inc van het product, dus de basisklasse van de gegenereerde client wordt voor C++Builder helemaal niet gecompileerd.

De specificatie wordt niet omgezet

Exitcode 7 betekent dat het document niet kon worden omgezet naar een geldig OpenAPI 3-document. YAML en Swagger 2.0 worden lokaal afgehandeld; de externe converter achter -r is de noodoplossing en uploadt het hele bestand naar een server die eSeGeCe niet beheert.

Verder verdiepen

Voorbij de eerste client

Vier richtingen, allemaal vanuit dezelfde generator.

Genereer een server, geen client

Geef -s mee en de generator geeft in plaats daarvan een serverstub uit. De serverdemo's tonen hoe de uitgegeven operaties worden gedispatcht en gevalideerd tegen de specificatie.

sgcOpenAPI Server

Gebruik de kant-en-klare SDK's

Meer dan duizend specificaties zijn al gegenereerd en worden meegeleverd, waaronder AWS, Azure, Google en Microsoft. Compileer het package dat je wilt en sla de generatiestap helemaal over.

De meegeleverde API's

Beperk wat je genereert

-x sluit operaties uit op basis van werkwoord en eindpunt en -p snoeit de klassen weg die geen enkele overgebleven operatie gebruikt. Bij een grote specificatie is dit het verschil tussen een unit die je kunt openen en een die je niet kunt openen.

De parser

Voeg authenticatie toe

De gegenereerde client heeft een eigenschap Authentication en -a kiest het schema tijdens het genereren: geen, basic, token, OAuth2 of JWT.

sgcOpenAPI-functies

Bronnen

Referentie, demo's en documentatie

Demoprojecten zitten in de download, onder Demos\: kant-en-klare SDK's, een gegenereerde client en twee servervoorbeelden.

	Wat sgcOpenAPI doet De parser, de generator en het servercomponent op één pagina.	Openen
	De parser Hoe een specificatie wordt gelezen, gevalideerd en omgezet naar Pascal-types.	Openen
	Het servercomponent Een API serveren vanuit een specificatie in plaats van er een te gebruiken.	Openen
	Meegeleverde API's De kant-en-klare SDK's die kant-en-klaar worden geleverd om te compileren.	Openen
	Download de proefversie De generator en de broncode, beperkt in tijd.	Openen
	Wat is OpenAPI Achtergrond, als het specificatieformaat zelf nieuw voor je is.	Openen

Verder lezen: een Delphi-client genereren vanuit OpenAPI, schema's bundelen, sgcOpenAPI vergeleken met swagger-codegen en de OpenAPI-server. Elk product heeft zijn eigen snelstart, te vinden op de pagina Aan de slag.

FAQ

Vragen over de sgcOpenAPI-snelstart

Geen. sgcOpenAPI is een codegenerator en een runtimebibliotheek en registreert niets op het IDE-palet. Er zit helemaal geen designtime-package in het product. Je voert sgcOpenAPI.exe uit op een specificatie, het schrijft één Pascal-unit en je voegt die unit toe aan je project. Daarin geeft GetOpenAPIClient een kant-en-klaar clientobject terug met één methode per operatie.

De tool toont die in zijn eigen help: sgcOpenAPI.exe -i "c:\openapi.json" -o "c:\openapi.pas". Beide schakelaars zijn verplicht. -i neemt een lokaal bestand of een URL en zowel JSON als YAML wordt geaccepteerd. -o is de Pascal-unit die wordt geschreven. Een waarde kan ook na een dubbele punt worden toegevoegd, zoals in -i:"c:\openapi.json".

Op twee manieren. De tool drukt File successfully created af, gevolgd door het uitvoerpad, en stelt een exitcode in die je in een buildscript kunt testen. De codes zijn 0 geslaagd, 1 fout, 2 ongeldige licentie, 3 ongeldige schakelaar, 4 ongeldig configuratiebestand, 5 ongeldig invoerbestand, 6 ongeldig uitvoerbestand en 7 de specificatie kon niet worden omgezet naar een geldig OpenAPI 3-document. Fouten gaan altijd naar standard error.

De gegenereerde methode geeft een responsobject terug dat is afgeleid van TsgcOpenAPIResponse. Lees eerst IsSuccessful. Als die false is, bevat ResponseError de melding en ResponseCode de HTTP-status. Geef het responsobject vrij zodra je ermee klaar bent, wat de meegeleverde demo doet in een try finally.

De gegenereerde client niet. SGC_HTTP_OPENAPI, dat de volledige interface van sgcHTTP_OpenAPI_Client.pas omsluit, wordt gedefinieerd binnen een {$IFNDEF BCB} op regel 702 van de sgcVer.inc van het product, dus onder C++Builder compileert die unit tot niets en heeft de gegenereerde code geen basisklasse. Genereer voor Delphi.

De gegenereerde code richt zich op Delphi 7 en hoger. De getypeerde responsobjecten vereisen XE7 of hoger en de meegeleverde demo maakt dat expliciet met {$IF CompilerVersion >= 28.0}: boven die grens krijg je een responsobject met getypeerde velden, eronder geeft dezelfde methode een gewone string terug. Behoud de beveiliging als je project op beide moet bouwen.

Ja. Geef -s mee en de generator geeft in plaats van een client een serverstub uit met code-first-attributen. De build die als sgcOpenAPI wordt geleverd, definieert SGC_HTTP_OPENAPI_SERVER op regel 11 van de sgcVer.inc, dus de serverkant is in elke licentie aanwezig. Twee serverdemo's zitten onder Demos\30.Server.

Niet tenzij je erom vraagt. YAML wordt lokaal gelezen en een Swagger 2.0-document wordt lokaal omgezet naar OpenAPI 3. De schakelaar -r, die standaard uit staat, staat een terugval toe naar de openbare converter op converter.swagger.io, en de helptekst zegt duidelijk dat hiermee het volledige bestand wordt geüpload naar een server die eSeGeCe niet beheert. Laat die uit voor alles wat vertrouwelijk is.

sgcOpenAPI in vijf minuten