Szybki start sgcOpenAPI

W skrócie

Nie ma komponentu do upuszczenia

To jedyna rzecz, którą trzeba zrozumieć przed startem. sgcOpenAPI niczego nie rejestruje na palecie IDE i nie zawiera pakietu czasu projektowania. Przepływ pracy to najpierw generowanie, potem użycie.

Narzędzie

sgcOpenAPI.exe, które jest jednocześnie kreatorem graficznym i wierszem poleceń. Odczytuje specyfikację i zapisuje jeden plik .pas.

Co zapisuje

Jednostkę zawierającą klasę klienta pochodną od TsgcOpenAPI_Client, jedną metodę na operację, klasy żądań i odpowiedzi oraz funkcję GetOpenAPIClient, która zwraca gotowy singleton.

Jak go wywołać

Dodaj wygenerowaną jednostkę do projektu, umieść ją w klauzuli uses i wywołaj GetOpenAPIClient.YourOperation(...). Wynikiem jest obiekt odpowiedzi, który zwalniasz, gdy z nim skończysz.

Pakiety

W pakiecie jest pięć pakietów uruchomieniowych z gotowymi zestawami SDK dla AWS, Azure, Google i Microsoft. Służą do kompilowania, a nie do instalowania, ponieważ nie ma strony palety do dodania.

Zanim zaczniesz

Wymagania i edycje

Kolumna edycji to define, który ogranicza kod, wraz z linią w Source/sgcVer.inc samego produktu.

Co	Wartość
IDE	Od Delphi 7 do RAD Studio 13 dla wygenerowanego kodu. Typowane obiekty odpowiedzi wymagają XE7 lub nowszego, a dostarczane demo chroni je przez `{$IF CompilerVersion >= 28.0}`. Poniżej tej wersji wygenerowana metoda zwraca zwykły tekst.
C++Builder	Nieobsługiwany dla wygenerowanego klienta. `SGC_HTTP_OPENAPI`, który obejmuje całość `sgcHTTP_OpenAPI_Client.pas`, jest zdefiniowany wewnątrz `{$IFNDEF BCB}` w linii 702 pliku `sgcVer.inc` produktu, więc kompilacja C++Builder zamienia tę jednostkę w nic.
Edycja	Kompilacje sgcOpenAPI są przypięte do dwóch najniższych poziomów. Linie od 7 do 10 jego `sgcVer.inc` to `{$IFDEF SGC_OPENAPI}`, a następnie `{$UNDEF SGC_EDT_PRO}`, `{$UNDEF SGC_EDT_ENT}` i `{$UNDEF SGC_EDT_ALL}`, co zostawia zdefiniowane Core i Standard. Poziomy komercyjne różnią się liczbą stanowisk, a nie funkcjami.
Generowanie serwera	Ta sama kompilacja definiuje `SGC_HTTP_OPENAPI_SERVER` w linii 11, więc generator potrafi wyemitować szkielet serwera oprócz klienta. Przekaż `-s` w wierszu poleceń.
Platformy	Brak warunku systemu operacyjnego na poziomie jednostki. Jedyne warunki w jednostce bazowej wygenerowanego klienta to zwykły import `{$IFDEF MSWINDOWS}` i zamiany typu identyfikatora wątku, więc kompilują się Windows, macOS, Linux, Android i iOS.
Aktywacja licencji	Jeśli komputer nie został aktywowany, przekaż `-user` i `-password` w wierszu poleceń, w przeciwnym razie uruchomienie kończy się kodem 2.

Generator akceptuje JSON i YAML i odczytuje oba lokalnie. Dokument Swagger 2.0 jest również konwertowany do OpenAPI 3 lokalnie. Zdalny konwerter jest opcjonalny, przez -r, i wysyła twoją specyfikację na serwer strony trzeciej, więc pozostaje wyłączony, dopóki o to nie poprosisz.

Krok 1

Zainstaluj i wygeneruj

Nie ma pakietu czasu projektowania do zainstalowania, więc instalacja jest krótsza niż w pozostałych produktach.

1. Rozpakuj

Rozpakuj pobrany plik do folderu, który poniżej nazywamy {$DIR}. Dostajesz Demos\, Bin\ i Source\.

2. Ścieżka biblioteki

Tools, Options, Library. Dodaj {$DIR}\Source, aby wygenerowane jednostki i klasa bazowa klienta były rozpoznawane. Do IDE nie ma nic do zainstalowania.

3. Opcjonalnie, skompiluj gotowy SDK

Jeśli chcesz użyć jednego z dołączonych SDK, otwórz odpowiedni pakiet uruchomieniowy w {$DIR}\Packages\ i skompiluj go. To pakiety uruchomieniowe, więc kompiluj, a nie instaluj.

4. Wygeneruj klienta

Uruchom Bin\sgcOpenAPI.exe dla kreatora lub użyj wiersza poleceń. Jedno wejście, jedno wyjście i masz jednostkę.

5. Dodaj jednostkę do projektu

Umieść wygenerowany .pas obok swoich pozostałych jednostek, dodaj go do projektu i umieść w klauzuli uses. To cała integracja.

QuickStart

Specyfikacja na wejściu, działający klient na wyjściu

Jedno polecenie generuje jednostkę. Jedno wywołanie jej używa. Trzecia karta pokazuje przełączniki warte poznania pierwszego dnia.

wiersz poleceń

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

File successfully created geolocation.pas

Oba przełączniki są obowiązkowe. -i przyjmuje plik lokalny lub adres URL i akceptuje JSON i YAML, a -o to jednostka Pascala do zapisania. W tym samym pliku wykonywalnym jest kreator graficzny, jeśli wolisz klikać. Dodaj wygenerowany .pas do projektu i jest gotowy do użycia.

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 jest generowany w jednostce i nie przyjmuje parametrów. Jedna metoda na operację, nazwana od identyfikatora operacji. Obiekt odpowiedzi musisz zwolnić sam, dlatego demo używa try finally. W wersjach Delphi przed XE7 wygenerowana metoda zwraca zamiast tego zwykły tekst, a dostarczane demo chroni typowaną ścieżkę przez {$IF CompilerVersion >= 28.0}.

wiersz poleceń

-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

Przy dużej specyfikacji -x i -p razem decydują o tym, czy jednostkę da się otworzyć w IDE, czy nie. -r też istnieje i jest celowo domyślnie wyłączony, ponieważ wysyła całą specyfikację do konwertera strony trzeciej.

Polecenie generowania to linia użycia wypisywana przez pomoc samego narzędzia. Wywołanie pochodzi z dostarczanego dema Demos\20.Client\abstractapi.com\geolocation\fGeolocation.pas, z kontrolkami formularza zastąpionymi literałami. To demo zawiera specyfikację i oczekuje, że sam wygenerujesz jednostkę, dlatego szybki start zaczyna się od generatora.

Krok 2

Sprawdź, czy generator się powiódł

Dwie rzeczy do obejrzenia, a jedną z nich można zautomatyzować.

Komunikat

Narzędzie wypisuje File successfully created, a po nim ścieżkę wyjściową. Błędy zawsze trafiają na standardowe wyjście błędów, więc cichy przebieg, który nic nie zapisał, nie jest niemy.

Kod wyjścia

0 sukces, 1 błąd, 2 nieprawidłowa licencja, 3 nieprawidłowy przełącznik, 4 nieprawidłowy plik konfiguracji, 5 nieprawidłowy plik wejściowy, 6 nieprawidłowy plik wyjściowy, 7 specyfikacji nie udało się przekonwertować na prawidłowy dokument OpenAPI 3. Sprawdzaj go w swoim skrypcie budującym.

Jednostka się kompiluje

Dodaj wygenerowany .pas do projektu i zbuduj. Powinien się kompilować, mając na ścieżce biblioteki tylko {$DIR}\Source.

`IsSuccessful`

W czasie działania mówi o tym obiekt odpowiedzi. Gdy ma wartość false, ResponseError niesie komunikat, a ResponseCode status HTTP.

Typowe problemy

Co zwykle idzie nie tak za pierwszym razem

Sześć problemów odpowiada za niemal każde pierwsze uruchomienie.

Szukasz komponentu na palecie

Nie ma żadnego. sgcOpenAPI nie rejestruje komponentów i nie zawiera pakietu czasu projektowania. Punktem integracji jest wygenerowana jednostka, a GetOpenAPIClient to sposób, by dotrzeć do klienta.

Jednostka wymieniona w demie nie istnieje

To oczekiwane. Dema zawierają specyfikację, a nie wygenerowaną jednostkę, więc najpierw uruchamiasz generator. Demo geolokalizacji potrzebuje jednostki o nazwie geolocation, która powstaje z geolocation.json.

Kod wyjścia 2

Licencja nie została aktywowana na tym komputerze. Przekaż -user i -password w wierszu poleceń.

Typowany obiekt odpowiedzi się nie kompiluje

Typowane odpowiedzi wymagają XE7 lub nowszego. Dostarczane demo chroni je przez {$IF CompilerVersion >= 28.0} i w starszych kompilatorach przechodzi na metodę zwracającą zwykły tekst. Zachowaj ten warunek, jeśli obsługujesz Delphi 7.

Nic się nie kompiluje w C++Builder

SGC_HTTP_OPENAPI jest zdefiniowany wewnątrz {$IFNDEF BCB} w linii 702 pliku sgcVer.inc produktu, więc bazowa klasa wygenerowanego klienta w ogóle nie jest kompilowana dla C++Builder.

Specyfikacja się nie konwertuje

Kod wyjścia 7 oznacza, że dokumentu nie dało się zamienić na prawidłowy dokument OpenAPI 3. YAML i Swagger 2.0 są obsługiwane lokalnie; zdalny konwerter za -r to wyjście awaryjne i wysyła cały plik na serwer, którego eSeGeCe nie kontroluje.

Zgłęb temat

Poza pierwszym klientem

Cztery kierunki, wszystkie z tego samego generatora.

Wygeneruj serwer, nie klienta

Przekaż -s, a generator wyemituje zamiast tego szkielet serwera. Dema serwera pokazują, jak emitowane operacje są kierowane i walidowane względem specyfikacji.

sgcOpenAPI Server

Użyj gotowych SDK

Ponad tysiąc specyfikacji jest już wygenerowanych i dołączonych, w tym AWS, Azure, Google i Microsoft. Skompiluj potrzebny pakiet i całkowicie pomiń krok generowania.

Dołączone API

Przytnij to, co generujesz

-x wyklucza operacje według czasownika i punktu końcowego, a -p usuwa klasy, których nie używa żadna pozostała operacja. Przy dużej specyfikacji decyduje to o tym, czy jednostkę da się otworzyć, czy nie.

Parser

Podłącz uwierzytelnianie

Wygenerowany klient ma właściwość Authentication, a -a wybiera schemat w czasie generowania: brak, basic, token, OAuth2 lub JWT.

Funkcje sgcOpenAPI

Zasoby

Dokumentacja, dema i materiały

Projekty demo znajdują się w pobranym pakiecie, w Demos\: gotowe SDK, wygenerowany klient i dwa przykłady serwera.

	Co robi sgcOpenAPI Parser, generator i komponent serwera na jednej stronie.	Otwórz
	Parser Jak specyfikacja jest odczytywana, walidowana i zamieniana na typy Pascala.	Otwórz
	Komponent serwera Udostępnianie API na podstawie specyfikacji zamiast korzystania z niego.	Otwórz
	Dołączone API Gotowe SDK dostarczane do skompilowania.	Otwórz
	Pobierz wersję próbną Generator i źródła, z ograniczeniem czasowym.	Otwórz
	Czym jest OpenAPI Tło, jeśli sam format specyfikacji jest dla ciebie nowy.	Otwórz

Powiązane lektury: generowanie klienta Delphi z OpenAPI, pakowanie schematów, sgcOpenAPI w porównaniu z swagger-codegen i serwer OpenAPI. Każdy produkt ma własny szybki start, wymieniony na stronie pierwszych kroków.

FAQ

Pytania o szybki start sgcOpenAPI

Żaden. sgcOpenAPI to generator kodu i biblioteka uruchomieniowa, i niczego nie rejestruje na palecie IDE. W produkcie w ogóle nie ma pakietu czasu projektowania. Uruchamiasz sgcOpenAPI.exe na specyfikacji, on zapisuje jedną jednostkę Pascala, a ty dodajesz tę jednostkę do projektu. W jej wnętrzu GetOpenAPIClient zwraca gotowy obiekt klienta z jedną metodą na operację.

Narzędzie wypisuje go we własnej pomocy: sgcOpenAPI.exe -i "c:\openapi.json" -o "c:\openapi.pas". Oba przełączniki są obowiązkowe. -i przyjmuje plik lokalny lub adres URL, a akceptowane są zarówno JSON, jak i YAML. -o to jednostka Pascala do zapisania. Wartość można też dołączyć po dwukropku, jak w -i:"c:\openapi.json".

Na dwa sposoby. Narzędzie wypisuje File successfully created, a po nim ścieżkę wyjściową, i ustawia kod wyjścia, który możesz sprawdzić w skrypcie budującym. Kody to 0 sukces, 1 błąd, 2 nieprawidłowa licencja, 3 nieprawidłowy przełącznik, 4 nieprawidłowy plik konfiguracji, 5 nieprawidłowy plik wejściowy, 6 nieprawidłowy plik wyjściowy oraz 7 specyfikacji nie udało się przekonwertować na prawidłowy dokument OpenAPI 3. Błędy zawsze trafiają na standardowe wyjście błędów.

Wygenerowana metoda zwraca obiekt odpowiedzi pochodny od TsgcOpenAPIResponse. Najpierw odczytaj IsSuccessful. Gdy ma wartość false, ResponseError niesie komunikat, a ResponseCode status HTTP. Zwolnij obiekt odpowiedzi, gdy z nim skończysz, co dostarczane demo robi w try finally.

Wygenerowany klient nie. SGC_HTTP_OPENAPI, który obejmuje cały interfejs sgcHTTP_OpenAPI_Client.pas, jest zdefiniowany wewnątrz {$IFNDEF BCB} w linii 702 pliku sgcVer.inc produktu, więc w C++Builder ta jednostka kompiluje się do niczego, a wygenerowany kod nie ma klasy bazowej. Generuj dla Delphi.

Wygenerowany kod celuje w Delphi 7 i nowsze. Typowane obiekty odpowiedzi wymagają XE7 lub nowszego, a dostarczane demo wyraża to jawnie przez {$IF CompilerVersion >= 28.0}: powyżej tej linii dostajesz obiekt odpowiedzi z typowanymi polami, poniżej ta sama metoda zwraca zwykły tekst. Zachowaj ten warunek, jeśli twój projekt musi się budować w obu.

Tak. Przekaż -s, a generator emituje szkielet serwera z atrybutami code-first zamiast klienta. Kompilacja dostarczana jako sgcOpenAPI definiuje SGC_HTTP_OPENAPI_SERVER w linii 11 swojego sgcVer.inc, więc strona serwera jest obecna w każdej licencji. W Demos\30.Server są dwa dema serwera.

Nie, chyba że o to poprosisz. YAML jest odczytywany lokalnie, a dokument Swagger 2.0 jest konwertowany do OpenAPI 3 lokalnie. Przełącznik -r, domyślnie wyłączony, pozwala wrócić do publicznego konwertera pod adresem converter.swagger.io, a tekst pomocy mówi wprost, że wysyła to cały plik na serwer, którego eSeGeCe nie kontroluje. Zostaw go wyłączonego dla wszystkiego, co jest poufne.

sgcOpenAPI w pięć minut