Serwer OpenAPI dla Delphi

W skrócie

TsgcOpenAPIServer

Jeden komponent Delphi, który zamienia specyfikację OpenAPI w działający, walidowany, samodokumentujący się serwer HTTP/2.

Klasa komponentu

TsgcOpenAPIServer

Transport

HTTP/1.1, HTTP/2, upgrade WebSocket, TLS przez OpenSSL lub SChannel

Formaty spec

OpenAPI 3.0, OpenAPI 3.1, Swagger 2.0 (konwertowany automatycznie)

Platformy

Windows, Linux, macOS — Delphi 7 do 13, C++Builder, FPC

Edycja

Standard / Professional / Enterprise — wszystkie zawierają serwer

Zbudowany na

Serwerze HTTP sgcWebSockets (ten sam pipeline TLS, HTTP/2, auth i logowania)

Dwa sposoby budowania

Spec-first lub Code-first — Ty wybierasz

Ten sam komponent działa w obu trybach. Zacznij od kontraktu YAML/JSON albo opisz API w Delphi i pozwól komponentowi opublikować specyfikację za Ciebie.

1. Spec-first

Załaduj openapi.yaml, podepnij handlery do operation ID i zacznij serwować. Routing, binding parametrów, content negotiation i walidacja pochodzą bezpośrednio z kontraktu — piszesz tylko logikę biznesową.

Najlepsze dla: zespołów ze wspólnym kontraktem projektowym, integracji API-led lub poliglotycznych back-endów, w których spec jest źródłem prawdy.

2. Code-first

Zarejestruj handlery w Pascalu z adnotacjami (path, czasownik HTTP, schemat żądania, schemat odpowiedzi, security). Komponent buduje dokument OpenAPI w runtime i wystawia go pod /openapi.json.

Najlepsze dla: szybkiego prototypowania, usług wewnętrznych lub przenoszenia istniejącej powierzchni REST TIdHTTPServer / DataSnap do samodokumentującego się API.

Szybki start

Działający serwer w 20 linijkach

Upuść komponent na formatkę, wskaż mu dokument OpenAPI, podepnij jedną operację, naciśnij Run. To cała konfiguracja.

Delphi

uses
  sgcOpenAPI_Server, sgcOpenAPI_Types, sgcHTTP_Server;

procedure TForm1.FormCreate(Sender: TObject);
begin
  FServer := TsgcOpenAPIServer.Create(nil);
  FServer.HTTPServer := sgcHTTPServer1;        // reuse the sgcWebSockets HTTP/2 server
  FServer.Spec.LoadFromFile('petstore.yaml');  // any OpenAPI 3.x doc
  FServer.PublishSpecPath := '/openapi.json';
  FServer.SwaggerUIPath   := '/docs';
  FServer.RedocPath       := '/redoc';

  // Bind one operation defined in the spec (operationId = "getPetById")
  FServer.OnOperation_getPetById :=
    procedure(const Ctx: TsgcOpenAPIContext)
    var
      oPet: TJSONObject;
    begin
      oPet := TJSONObject.Create;
      oPet.AddPair('id',     Ctx.PathParams['petId']);
      oPet.AddPair('name',   'Rex');
      oPet.AddPair('status', 'available');
      Ctx.RespondJSON(200, oPet);
    end;

  sgcHTTPServer1.Port   := 8080;
  sgcHTTPServer1.Active := True;
end;

Co dostajesz od razu z pudełka: GET /pets/{petId} obsługuje powyższy handler, GET /openapi.json zwraca specyfikację na żywo, GET /docs otwiera Swagger UI, GET /redoc otwiera Redoc — z HTTP/2 i TLS już włączonymi, jeśli sgcHTTPServer1 ma je skonfigurowane.

Routing

Parametry zadeklarowane w dokumencie OpenAPI są parsowane, sprawdzane typowo i wystawione przez jeden typowany kontekst. Niewłaściwe typy zwracają 400 Bad Request jeszcze zanim Twój handler się uruchomi.

Delphi

// spec snippet
//   /pets:
//     get:
//       operationId: listPets
//       parameters:
//         - name: limit       in: query    schema: { type: integer, maximum: 100 }
//         - name: status      in: query    schema: { type: string, enum: [available, pending, sold] }
//         - name: X-Tenant-Id in: header   required: true

FServer.OnOperation_listPets :=
  procedure(const Ctx: TsgcOpenAPIContext)
  var
    vLimit:  Integer;
    vStatus: string;
    vTenant: string;
  begin
    vLimit  := Ctx.QueryParamInt('limit', 20);     // default 20
    vStatus := Ctx.QueryParam   ('status', 'available');
    vTenant := Ctx.HeaderParam  ('X-Tenant-Id');   // required → validated

    Ctx.RespondJSON(200, PetRepo.List(vTenant, vStatus, vLimit));
  end;

Walidacja

Walidacja schematów w obu kierunkach

Każde przychodzące ciało żądania jest walidowane względem schematu requestBody operacji. Każda odpowiedź jest walidowana względem zadeklarowanego kodu statusu. Niezgodności zwracają problem-details w formacie RFC 7807 z diagnostyką na poziomie pola.

Walidacja żądań

Pola wymagane, koercja typów, członkostwo w enum, walidatory format (email, uuid, date-time, ipv4/6), minLength / maxLength, minimum / maximum, pattern, additionalProperties, oneOf / anyOf / allOf — wszystko wymuszane zanim uruchomi się Twój handler.

Walidacja odpowiedzi

Opcjonalna na produkcji, ścisła w developmencie. Pomaga złapać dzień, w którym Twój handler zwraca dodatkowe pole spoza kontraktu, zanim konsument w dół popsuje się.

Niestandardowe walidatory

Podepnij się pod OnBeforeValidate, aby dodać reguły domenowe (kod waluty jest wspierany, SKU istnieje, tenant jest aktywny). Zwraca tę samą kopertę RFC 7807 co wbudowane walidatory — dla jednolitego UX błędów.

JSON — przykładowa odpowiedź 400

{
  "type":   "https://example.com/probs/validation",
  "title":  "Request body failed schema validation",
  "status": 400,
  "errors": [
    { "path": "/email",    "message": "not a valid email address" },
    { "path": "/age",      "message": "value 213 exceeds maximum 120" },
    { "path": "/status",   "message": "value 'archived' not in enum [active,pending]" }
  ]
}

Bezpieczeństwo

Schematy auth podpięte prosto ze specyfikacji

Każdy zadeklarowany w dokumencie securityScheme jest egzekwowany automatycznie. Ty piszesz tylko wyszukiwanie poświadczeń — parsing, nagłówki challenge oraz odpowiedzi 401/403 załatwia komponent.

API Key

Header, query lub cookie. Wiele kluczy na operację. Porównanie w stałym czasie.

HTTP Basic / Bearer

RFC 7617 / RFC 6750 z obsługą realm. Poświadczenia nigdy nie trafiają do logów.

JWT (RS256 / ES256 / HS256)

Auto-pobieranie i cache JWKS. Sprawdzanie issuera, audience, wygaśnięcia i niestandardowych claimów.

OAuth2

Przepływy Authorization Code, Client Credentials, Password i Implicit. PKCE obsługiwane.

OpenID Connect

Dokument discovery ładowany z /.well-known/openid-configuration. ID token walidowany względem JWKS.

mTLS

Wymuszanie certyfikatu klienta per operacja. Common Name i SAN dostępne w kontekście.

Delphi — hook walidacji JWT

FServer.Security.JWT.JWKSUri := 'https://auth.example.com/.well-known/jwks.json';
FServer.Security.JWT.Audience := 'api.example.com';
FServer.Security.JWT.Issuer   := 'https://auth.example.com/';

FServer.OnAuthorize :=
  procedure(const Ctx: TsgcOpenAPIContext; var Allow: Boolean)
  begin
    // Token already verified. Apply business rule on a custom claim.
    Allow := Ctx.JWT.Claims['tenant'] = Ctx.PathParams['tenant'];
  end;

Samodokumentujące

Swagger UI i Redoc wbudowane

Bez zewnętrznych zależności, bez Node.js, bez swagger-codegen w pipeline'ie deploymentu. Oba UI są spakowane wewnątrz komponentu i serwowane prosto ze specyfikacji w runtime.

/openapi.json i /openapi.yaml

Dokument na żywo — zawsze zsynchronizowany z tym, co naprawdę serwuje serwer. Wskaż dowolny generator klientów (sgcOpenAPI, openapi-generator, oapi-codegen) na ten URL.

/docs — Swagger UI

Znajome, interaktywne Swagger UI — wypróbuj operacje, przeglądaj schematy, oglądaj przykłady. Konfigurowalny motyw, deepLinking i redirect OAuth2.

/redoc — Redoc

Schludny, trzy-panelowy układ Redoc dla dokumentacji API o statycznym charakterze. To samo źródło, inna prezentacja.

Formaty wire

Content negotiation zrobione dobrze

application/json

UTF-8, ścisły RFC 8259. Liczby, booleany, nulle, zagnieżdżone obiekty i tablice.

application/yaml

YAML 1.2 z parsingiem świadomym schematu. Przydatne do ciał żądań edytowanych ręcznie.

application/x-www-form-urlencoded

Klasyczne posty formularzy — związane ze schematem żądania jak każde inne ciało.

multipart/form-data

Uploady plików z limitami rozmiaru, allow listami typów MIME i bindingiem schematu per część.

text/event-stream (SSE)

Długo działające strumieniowane odpowiedzi — reużywa writera SSE z sgcWebSockets.

application/octet-stream

Surowe binarne pobieranie/uploadowanie z obsługą byte-range request.

Integracja

Jeden serwer HTTP, wiele powierzchni

TsgcOpenAPIServer podpina się do tego samego serwera HTTP/2 sgcWebSockets, który hostuje Twoje endpointy WebSocket, strumienie AI/LLM i pliki statyczne. Jeden port, jeden certyfikat TLS, jeden strumień logów.

Multipleksowanie HTTP/2

Setki operacji REST i długo żyjąca subskrypcja WebSocket dzielą to samo połączenie TLS. Klienci przeglądarkowi dostają handshake w jednym rundtripie, Ty masz mniej socketów do utrzymania przy życiu.

Promocja do WebSocket

Zadeklaruj x-sgc-upgrade: websocket na ścieżce, a komponent wykona upgrade RFC 6455 za Ciebie — ta sama operacja obsługuje zarówno REST, jak i dwukierunkowy streaming.

Trasy statycznych zasobów

Wrzuć build SPA pod /app w tym samym komponencie — czyste URL-e, gzip, brotli, ETag i HTTP/2 server-push gratis.

Gdzie błyszczy

Typowe wdrożenia

Publiczne API REST

Wersjonowane, kontraktowo testowane, z autogenerowanymi SDK, które Twoi klienci mogą pobrać z /openapi.json.

Wewnętrzne mikroserwisy

Kontrakty serwis-do-serwisu, które przeżywają refaktory — spec to test integracyjny.

Bramy przemysłowe / IoT

Urządzenia edge wystawiające udokumentowany REST control plane plus powierzchnię telemetrii MQTT lub WebSocket z tej samej binarki Delphi.

Odbiorniki webhooków

Payload webhooka każdego providera staje się typowanym rekordem Pascal — Stripe, GitHub, Twilio, Slack — z walidacją i idempotencją w komplecie.

Modernizacja legacy

Owiń stary back-end DataSnap lub RemObjects czystą powierzchnią OpenAPI bez przepisywania logiki biznesowej.

BFF (Backend-for-Frontend)

Zagreguj dwa lub trzy upstreamowe API za jedną specyfikacją w kształcie konsumenta — Twoja SPA lub aplikacja mobilna rozmawia z jednym, typowanym endpointem.

Lepiej razem