OpenAPI-Server für Delphi

TsgcOpenAPIServer veröffentlicht ein lebendes OpenAPI-3.x-Dokument, routet eingehende Requests anhand der Spezifikation, validiert Payloads in beide Richtungen und liefert eingebettete Swagger UI und Redoc — alles aus einer einzigen Delphi-Komponente auf dem sgcWebSockets-HTTP/2-Server.

OpenAPI 3.0 & 3.1
HTTP/2 + TLS 1.3
Swagger UI + Redoc
Spec-first oder Code-first

TsgcOpenAPIServer

Eine einzige Delphi-Komponente, die eine OpenAPI-Spezifikation in einen laufenden, validierten, selbstdokumentierenden HTTP/2-Server verwandelt.

Komponentenklasse

TsgcOpenAPIServer

Transport

HTTP/1.1, HTTP/2, WebSocket-Upgrade, TLS über OpenSSL oder SChannel

Spec-Formate

OpenAPI 3.0, OpenAPI 3.1, Swagger 2.0 (automatisch konvertiert)

Plattformen

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

Edition

Standard / Professional / Enterprise — alle enthalten den Server

Gebaut auf

sgcWebSockets-HTTP-Server (gleiche Pipeline für TLS, HTTP/2, Auth und Logging)

Spec-first oder Code-first — Du entscheidest

Dieselbe Komponente läuft in beiden Modi. Starte von einem YAML-/JSON-Vertrag oder beschreibe die API in Delphi und lass die Komponente die Spezifikation für dich veröffentlichen.

1. Spec-first

Lade openapi.yaml, binde Handler an Operation-IDs und starte. Routing, Parameter-Binding, Content Negotiation und Validierung kommen direkt aus dem Vertrag — du schreibst nur die Business-Logik.

Am besten für: Teams mit gemeinsamem Design-Vertrag, API-led Integration oder polyglotte Backends, in denen die Spec die Single Source of Truth ist.

2. Code-first

Registriere Handler in Pascal mit Annotationen (Path, Verb, Request-Schema, Response-Schema, Security). Die Komponente baut das OpenAPI-Dokument zur Laufzeit und stellt es unter /openapi.json bereit.

Am besten für: Rapid Prototyping, interne Services oder das Portieren einer bestehenden TIdHTTPServer-/DataSnap-REST-Oberfläche zu einer selbstdokumentierenden API.

Ein lauffähiger Server in 20 Zeilen

Setze die Komponente auf ein Formular, verweise sie auf ein OpenAPI-Dokument, binde eine Operation, drück Run. Mehr Setup gibt es nicht.

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;

Was du out of the box bekommst: GET /pets/{petId} bedient den obigen Handler, GET /openapi.json liefert die lebende Spec, GET /docs öffnet Swagger UI, GET /redoc öffnet Redoc — mit HTTP/2 und TLS bereits aktiv, wenn sgcHTTPServer1 sie konfiguriert hat.

Die im OpenAPI-Dokument deklarierten Parameter werden geparst, typgeprüft und über einen einzigen typisierten Context bereitgestellt. Falsche Typen liefern 400 Bad Request, bevor dein Handler überhaupt läuft.

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;

Schema-Validierung in beide Richtungen

Jeder eingehende Body wird gegen das requestBody-Schema der Operation validiert. Jede Response wird gegen den deklarierten Statuscode geprüft. Abweichungen liefern Problem-Details nach RFC 7807 mit feldgenauer Diagnose.

Request-Validierung

Pflichtfelder, Typkoerzion, Enum-Mitgliedschaft, format-Validatoren (email, uuid, date-time, ipv4/6), minLength / maxLength, minimum / maximum, pattern, additionalProperties, oneOf / anyOf / allOf — alles erzwungen, bevor dein Handler läuft.

Response-Validierung

In Produktion optional, in der Entwicklung strikt. Hilft dir, den Tag zu erwischen, an dem dein Handler ein zusätzliches Feld liefert, das nicht im Vertrag steht — bevor ein nachgelagerter Konsument bricht.

Eigene Validatoren

Klinke dich in OnBeforeValidate ein, um Domain-Regeln zu ergänzen (Währungscode ist unterstützt, SKU existiert, Tenant ist aktiv). Liefert denselben RFC-7807-Envelope wie die eingebauten Validatoren — für eine einheitliche Fehler-UX.

JSON — Beispiel-Response 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]" }
  ]
}

Auth-Schemes direkt aus der Spec verdrahtet

Jedes im Dokument deklarierte securityScheme wird automatisch erzwungen. Du schreibst nur die Credential-Lookup-Logik — die Komponente übernimmt Parsing, Challenge-Header und die 401/403-Antworten.

API Key

Header, Query oder Cookie. Mehrere Keys pro Operation. Vergleich in konstanter Zeit.

HTTP Basic / Bearer

RFC 7617 / RFC 6750 mit Realm-Unterstützung. Credentials werden nie geloggt.

JWT (RS256 / ES256 / HS256)

JWKS automatisch laden und cachen. Prüfung von Issuer, Audience, Ablauf und Custom Claims.

OAuth2

Authorization Code, Client Credentials, Password und Implicit Flow. PKCE unterstützt.

OpenID Connect

Discovery-Dokument geladen aus /.well-known/openid-configuration. ID-Token gegen JWKS validiert.

mTLS

Client-Zertifikat pro Operation erzwingbar. Common Name und SAN im Context verfügbar.

Delphi — JWT-Validierungs-Hook
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;

Swagger UI & Redoc eingebettet

Keine externen Abhängigkeiten, kein Node.js, kein swagger-codegen in der Deployment-Pipeline. Beide UIs sind in der Komponente gebündelt und werden zur Laufzeit direkt aus der Spec ausgeliefert.

/openapi.json & /openapi.yaml

Das lebende Dokument — immer synchron mit dem, was der Server tatsächlich ausliefert. Richte jeden Client-Generator (sgcOpenAPI, openapi-generator, oapi-codegen) auf diese URL.

/docs — Swagger UI

Die bekannte interaktive Swagger UI — Operationen ausprobieren, Schemas durchsehen, Beispiele ansehen. Konfigurierbares Theme, deepLinking und OAuth2-Redirect.

/redoc — Redoc

Das aufgeräumte Drei-Spalten-Layout von Redoc für API-Doku im statischen Look. Gleiche Quelle, andere Darstellung.

Content Negotiation richtig gemacht

application/json

UTF-8, strikt nach RFC 8259. Zahlen, Booleans, Nulls, verschachtelte Objekte und Arrays.

application/yaml

YAML 1.2 mit schemabewusstem Parsing. Nützlich für handgepflegte Request-Bodies.

application/x-www-form-urlencoded

Klassische Formular-Posts — an das Request-Schema gebunden wie jeder andere Body.

multipart/form-data

Datei-Uploads mit Größenlimits, MIME-Type-Allowlists und Schema-Bindung pro Part.

text/event-stream (SSE)

Langlaufende gestreamte Antworten — nutzt den SSE-Writer von sgcWebSockets wieder.

application/octet-stream

Roher binärer Download/Upload mit Byte-Range-Request-Unterstützung.

Ein HTTP-Server, viele Oberflächen

TsgcOpenAPIServer dockt an denselben sgcWebSockets-HTTP/2-Server an, der auch deine WebSocket-Endpunkte, AI-/LLM-Streams und statischen Dateien hostet. Ein Port, ein TLS-Zertifikat, ein Log-Stream.

HTTP/2-Multiplexing

Hunderte von REST-Operationen und ein langlebiges WebSocket-Abo teilen sich dieselbe TLS-Verbindung. Browser-Clients bekommen einen Round-Trip-Handshake, du hast weniger Sockets am Leben zu halten.

WebSocket-Promotion

Deklariere x-sgc-upgrade: websocket auf einem Pfad und die Komponente führt das RFC-6455-Upgrade für dich aus — dieselbe Operation macht REST und bidirektionales Streaming.

Static-Asset-Routen

Leg den SPA-Build unter /app auf dieselbe Komponente — saubere URLs, gzip, brotli, ETag und HTTP/2-Server-Push gratis.

Typische Deployments

Öffentliche REST-APIs

Versioniert, vertraglich getestet, mit automatisch generierten SDKs, die deine Kunden von /openapi.json herunterladen können.

Interne Microservices

Service-zu-Service-Verträge, die Refactorings überleben — die Spec ist der Integrationstest.

Industrial-/IoT-Gateways

Edge-Geräte mit dokumentierter REST-Control-Plane plus MQTT- oder WebSocket-Telemetrie aus demselben Delphi-Binary.

Webhook-Empfänger

Jedes Provider-Webhook-Payload wird zu einem typisierten Pascal-Record — Stripe, GitHub, Twilio, Slack — mit Validierung und Idempotenz eingebaut.

Legacy-Modernisierung

Verpacke ein altes DataSnap- oder RemObjects-Backend hinter einer sauberen OpenAPI-Oberfläche, ohne die Business-Logik neu zu schreiben.

BFF (Backend-for-Frontend)

Aggregiere zwei oder drei Upstream-APIs hinter einer konsumentenförmigen Spec — deine SPA oder Mobile App spricht mit einem einzigen typisierten Endpunkt.

Kombiniert mit

OpenAPI-Parser

Lade jede externe Spec in dasselbe Modell, das auch der Server nutzt — gleiche Validierung, gleiches Typsystem, gleiche Security-Primitive.

Vorgefertigte Cloud-SDKs

Über 1.195 generierte SDKs für AWS, Azure, GCP, Stripe, GitHub, Kubernetes und mehr — dein Server kann jedes davon mit derselben Komponentenfamilie ansprechen.

sgcWebSockets

WebSocket, MQTT, AMQP, WebRTC, AI/LLM, IoT — alles, was der HTTP-Server neben deiner REST-Oberfläche hosten kann.

sgcSign

Signiere Request- und Response-Bodies mit XAdES / PAdES / CAdES für regulierte Branchen — eIDAS-Integrität auf jeder Operation.

Baue deinen ersten OpenAPI-Server in Minuten

Lade die kostenlose Testversion herunter. Der komplette Server, beide UIs, jedes Auth-Schema — keine Feature-Limits, keine Zeitbombe während der Evaluierung.