Server OpenAPI per Delphi

In sintesi

TsgcOpenAPIServer

Un unico componente Delphi che trasforma una specifica OpenAPI in un server HTTP/2 in esecuzione, validato e auto-documentato.

Classe del componente

TsgcOpenAPIServer

Trasporto

HTTP/1.1, HTTP/2, upgrade WebSocket, TLS via OpenSSL o SChannel

Formati di spec

OpenAPI 3.0, OpenAPI 3.1, Swagger 2.0 (convertito automaticamente)

Piattaforme

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

Edizione

Standard / Professional / Enterprise — tutte includono il server

Basato su

Server HTTP di sgcWebSockets (stessa pipeline TLS, HTTP/2, auth e logging)

Due modi per costruire

Spec-first o Code-first — Scegli tu

Lo stesso componente gira in entrambe le modalità. Parti da un contratto YAML/JSON, oppure descrivi l'API in Delphi e lascia che sia il componente a pubblicare la specifica per te.

1. Spec-first

Carica openapi.yaml, lega gli handler agli operation ID e inizia a servire. Routing, binding dei parametri, content negotiation e validazione arrivano direttamente dal contratto — scrivi solo la logica di business.

Ideale per: team con un contratto di design condiviso, integrazione API-led o back-end poliglotti dove la spec è la fonte di verità.

2. Code-first

Registra gli handler in Pascal con annotazioni (path, verbo, schema della request, schema della response, sicurezza). Il componente costruisce il documento OpenAPI a runtime e lo espone su /openapi.json.

Ideale per: prototipazione rapida, servizi interni o porting di una superficie REST TIdHTTPServer / DataSnap esistente verso un'API auto-documentata.

Guida Rapida

Un Server Funzionante in 20 Righe

Trascina il componente su una form, puntalo a un documento OpenAPI, lega un'operazione, premi Run. Questa è tutta la configurazione.

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;

Cosa ottieni subito: GET /pets/{petId} serve l'handler qui sopra, GET /openapi.json restituisce la spec live, GET /docs apre Swagger UI, GET /redoc apre Redoc — con HTTP/2 e TLS già attivi se sgcHTTPServer1 li ha configurati.

Routing

I parametri dichiarati nel documento OpenAPI vengono parsati, controllati nei tipi ed esposti tramite un unico context tipizzato. I tipi sbagliati restituiscono 400 Bad Request prima ancora che il tuo handler venga eseguito.

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;

Validazione

Validazione degli schemi in entrambe le direzioni

Ogni body in entrata viene validato rispetto allo schema requestBody dell'operazione. Ogni risposta viene validata rispetto al codice di stato dichiarato. Le incongruenze restituiscono problem-details RFC 7807 con diagnostica a livello di campo.

Validazione delle richieste

Campi obbligatori, coercizione dei tipi, appartenenza a enum, validatori di format (email, uuid, date-time, ipv4/6), minLength / maxLength, minimum / maximum, pattern, additionalProperties, oneOf / anyOf / allOf — tutto applicato prima che il tuo handler venga eseguito.

Validazione delle risposte

Opzionale in produzione, stringente in sviluppo. Ti aiuta a intercettare il giorno in cui il tuo handler restituisce un campo extra non previsto dal contratto, prima che un consumatore a valle si rompa.

Validatori personalizzati

Aggancia OnBeforeValidate per aggiungere regole di dominio (codice valuta supportato, SKU esistente, tenant attivo). Restituisce lo stesso envelope RFC 7807 dei validatori integrati, per una UX di errore uniforme.

JSON — esempio risposta 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]" }
  ]
}

Sicurezza

Schemi di Auth Cablati Dalla Spec

Ogni securityScheme dichiarato nel documento viene applicato automaticamente. Tu scrivi solo il lookup delle credenziali — il componente si occupa di parsing, header di challenge e risposte 401/403.

API Key

Header, query o cookie. Più chiavi per operazione. Confronto a tempo costante.

HTTP Basic / Bearer

RFC 7617 / RFC 6750 con supporto realm. Le credenziali non vengono mai loggate.

JWT (RS256 / ES256 / HS256)

JWKS auto-fetch e cache. Controlli su issuer, audience, scadenza e claim personalizzati.

OAuth2

Flussi Authorization Code, Client Credentials, Password e Implicit. PKCE supportato.

OpenID Connect

Documento di discovery caricato da /.well-known/openid-configuration. ID token validato contro JWKS.

mTLS

Enforcement del certificato client per operazione. Common Name e SAN disponibili nel context.

Delphi — hook di validazione 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;

Auto-documentato

Swagger UI e Redoc Integrati

Nessuna dipendenza esterna, niente Node.js, niente swagger-codegen nella pipeline di deploy. Entrambe le UI sono incluse nel componente e servite direttamente dalla spec a runtime.

/openapi.json e /openapi.yaml

Il documento dal vivo — sempre allineato con quello che il server serve davvero. Punta qualsiasi generatore di client (sgcOpenAPI, openapi-generator, oapi-codegen) a questa URL.

/docs — Swagger UI

La familiare Swagger UI interattiva — prova le operazioni, esplora gli schemi, vedi esempi. Tema configurabile, deepLinking e redirect OAuth2.

/redoc — Redoc

Il pulito layout a tre pannelli di Redoc per una documentazione API dall'aspetto statico. Stessa fonte, presentazione diversa.

Formati wire

Content Negotiation fatta bene

application/json

UTF-8, stretto RFC 8259. Numeri, booleani, null, oggetti annidati e array.

application/yaml

YAML 1.2 con parsing schema-aware. Utile per request body editati a mano.

application/x-www-form-urlencoded

Classici post di form — legati allo schema della richiesta come qualsiasi altro body.

multipart/form-data

Upload di file con limiti di dimensione, allow list di MIME type e binding di schema per parte.

text/event-stream (SSE)

Risposte streamed di lunga durata — riusa il writer SSE di sgcWebSockets.

application/octet-stream

Download/upload binario raw con supporto per byte-range request.

Integrazione

Un server HTTP, molte superfici

TsgcOpenAPIServer si innesta nello stesso server HTTP/2 di sgcWebSockets che ospita i tuoi endpoint WebSocket, gli stream AI/LLM e i file statici. Una porta, un certificato TLS, uno stream di log.

Multiplexing HTTP/2

Centinaia di operazioni REST e una sottoscrizione WebSocket di lunga durata condividono la stessa connessione TLS. I client browser ottengono un handshake in una sola andata e ritorno, tu hai meno socket da tenere vivi.

Promozione a WebSocket

Dichiara x-sgc-upgrade: websocket su un path e il componente esegue l'upgrade RFC 6455 per te — la stessa operazione fa sia REST che streaming bidirezionale.

Route per asset statici

Metti la build della SPA sotto /app sullo stesso componente — URL puliti, gzip, brotli, ETag e HTTP/2 server-push gratis.

Dove brilla

Deployment tipici

API REST pubbliche

Versionate, testate per contratto, con SDK auto-generati che i tuoi clienti possono scaricare da /openapi.json.

Microservizi interni

Contratti servizio-a-servizio che sopravvivono ai refactor — la spec è il test di integrazione.

Gateway industriali / IoT

Dispositivi edge che espongono un control plane REST documentato più una superficie di telemetria MQTT o WebSocket dallo stesso binario Delphi.

Ricevitori di webhook

Il payload del webhook di ogni provider diventa un record Pascal tipizzato — Stripe, GitHub, Twilio, Slack — con validazione e idempotenza integrate.

Modernizzazione di legacy

Avvolgi un vecchio back-end DataSnap o RemObjects dietro una superficie OpenAPI pulita senza riscrivere la logica di business.

BFF (Backend-for-Frontend)

Aggrega due o tre API upstream dietro un'unica spec a forma di consumatore — la tua SPA o app mobile parla con un singolo endpoint tipizzato.

Meglio insieme