Serveur OpenAPI pour Delphi

En un coup d'œil

TsgcOpenAPIServer

Un seul composant Delphi qui transforme une spécification OpenAPI en serveur HTTP/2 fonctionnel, validé et auto-documenté.

Classe du composant

TsgcOpenAPIServer

Transport

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

Formats de spec

OpenAPI 3.0, OpenAPI 3.1, Swagger 2.0 (converti automatiquement)

Plateformes

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

Édition

Standard / Professional / Enterprise — toutes incluent le serveur

Construit sur

Serveur HTTP sgcWebSockets (même pipeline TLS, HTTP/2, auth et logs)

Deux façons de construire

Spec-first ou Code-first — à vous de choisir

Le même composant fonctionne dans les deux modes. Partez d'un contrat YAML/JSON, ou décrivez l'API en Delphi et laissez le composant publier la spécification pour vous.

1. Spec-first

Chargez openapi.yaml, liez les handlers aux operation IDs et lancez le serveur. Les routes, le binding des paramètres, la négociation de contenu et la validation viennent directement du contrat — vous n'écrivez que la logique métier.

Idéal pour : les équipes avec un contrat de design partagé, l'intégration API-led ou les back-ends polyglottes où la spec fait foi.

2. Code-first

Enregistrez les handlers en Pascal avec des annotations (path, verbe, schéma de requête, schéma de réponse, sécurité). Le composant construit le document OpenAPI à l'exécution et l'expose sur /openapi.json.

Idéal pour : le prototypage rapide, les services internes ou le portage d'une surface REST TIdHTTPServer / DataSnap existante vers une API auto-documentée.

Démarrage rapide

Un serveur opérationnel en 20 lignes

Déposez le composant sur une fiche, pointez-le vers un document OpenAPI, liez une opération, appuyez sur Run. C'est toute la configuration.

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;

Ce que vous obtenez d'emblée : GET /pets/{petId} sert le handler ci-dessus, GET /openapi.json renvoie la spec en direct, GET /docs ouvre Swagger UI, GET /redoc ouvre Redoc — avec HTTP/2 et TLS déjà actifs si sgcHTTPServer1 est configuré pour.

Routage

Les paramètres déclarés dans le document OpenAPI sont parsés, vérifiés en type et exposés via un unique contexte typé. Les types incorrects renvoient 400 Bad Request avant même que votre handler ne s'exécute.

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;

Validation

Validation de schéma dans les deux sens

Chaque body entrant est validé contre le schéma requestBody de l'opération. Chaque réponse est validée contre le code de statut déclaré. Les écarts renvoient des problem-details RFC 7807 avec un diagnostic au niveau du champ.

Validation des requêtes

Champs obligatoires, coercition de type, appartenance à un enum, validateurs format (email, uuid, date-time, ipv4/6), minLength / maxLength, minimum / maximum, pattern, additionalProperties, oneOf / anyOf / allOf — tout est appliqué avant que votre handler ne s'exécute.

Validation des réponses

Optionnelle en production, stricte en développement. Vous aide à détecter le jour où votre handler renvoie un champ supplémentaire absent du contrat avant qu'un consommateur en aval ne casse.

Validateurs personnalisés

Branchez-vous sur OnBeforeValidate pour ajouter des règles métier (code devise supporté, SKU existant, tenant actif). Renvoie la même enveloppe RFC 7807 que les validateurs intégrés pour une UX d'erreur uniforme.

JSON — exemple de réponse 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]" }
  ]
}

Sécurité

Schémas d'auth câblés depuis la spec

Chaque securityScheme déclaré dans le document est appliqué automatiquement. Vous n'écrivez que la recherche des identifiants — le composant gère le parsing, les en-têtes de challenge et les réponses 401/403.

API Key

Header, query ou cookie. Plusieurs clés par opération. Comparaison en temps constant.

HTTP Basic / Bearer

RFC 7617 / RFC 6750 avec support de realm. Les identifiants ne sont jamais loggés.

JWT (RS256 / ES256 / HS256)

Récupération et cache automatiques du JWKS. Vérification de l'issuer, de l'audience, de l'expiration et des claims personnalisés.

OAuth2

Flux Authorization Code, Client Credentials, Password et Implicit. PKCE supporté.

OpenID Connect

Document de discovery chargé depuis /.well-known/openid-configuration. ID token validé contre JWKS.

mTLS

Exigence d'un certificat client par opération. Common Name et SAN disponibles dans le contexte.

Delphi — hook de validation 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-documenté

Swagger UI et Redoc embarqués

Aucune dépendance externe, pas de Node.js, pas de swagger-codegen dans la pipeline de déploiement. Les deux UI sont incluses dans le composant et servies directement depuis la spec à l'exécution.

/openapi.json et /openapi.yaml

Le document en direct — toujours synchronisé avec ce que le serveur sert réellement. Pointez n'importe quel générateur de client (sgcOpenAPI, openapi-generator, oapi-codegen) sur cette URL.

/docs — Swagger UI

L'interface Swagger UI interactive bien connue — essayez les opérations, parcourez les schémas, consultez les exemples. Thème, deepLinking et redirect OAuth2 configurables.

/redoc — Redoc

Le layout épuré à trois panneaux de Redoc pour une documentation d'API au rendu statique. Même source, présentation différente.

Formats wire

Négociation de contenu bien faite

application/json

UTF-8, strict RFC 8259. Nombres, booléens, nulls, objets imbriqués et tableaux.

application/yaml

YAML 1.2 avec parsing conscient du schéma. Utile pour les bodies édités à la main.

application/x-www-form-urlencoded

Posts de formulaire classiques — liés au schéma de la requête comme n'importe quel autre body.

multipart/form-data

Uploads de fichiers avec limites de taille, allow lists de MIME-types et binding de schéma par partie.

text/event-stream (SSE)

Réponses streamées de longue durée — réutilise le writer SSE de sgcWebSockets.

application/octet-stream

Téléchargement/upload binaire brut avec support des byte-range requests.

Intégration

Un seul serveur HTTP, plusieurs surfaces

TsgcOpenAPIServer se branche sur le même serveur HTTP/2 sgcWebSockets qui héberge vos endpoints WebSocket, vos streams IA/LLM et vos fichiers statiques. Un port, un certificat TLS, un flux de logs.

Multiplexage HTTP/2

Des centaines d'opérations REST et un abonnement WebSocket longue durée partagent la même connexion TLS. Les clients navigateur n'ont qu'un seul aller-retour de handshake, vous avez moins de sockets à maintenir.

Promotion en WebSocket

Déclarez x-sgc-upgrade: websocket sur un path et le composant effectue l'upgrade RFC 6455 pour vous — la même opération fait à la fois REST et streaming bidirectionnel.

Routes d'assets statiques

Déposez le build de la SPA sous /app sur le même composant — URLs propres, gzip, brotli, ETag et server-push HTTP/2 gratuits.

Où il brille

Déploiements typiques

APIs REST publiques

Versionnées, testées par contrat, avec des SDK auto-générés que vos clients peuvent télécharger depuis /openapi.json.

Microservices internes

Contrats de service à service qui survivent aux refactorings — la spec est le test d'intégration.

Passerelles industrielles / IoT

Équipements edge exposant un plan de contrôle REST documenté plus une surface télémétrie MQTT ou WebSocket depuis le même binaire Delphi.

Récepteurs de webhooks

Chaque payload de webhook fournisseur devient un record Pascal typé — Stripe, GitHub, Twilio, Slack — avec validation et idempotence intégrées.

Modernisation de legacy

Enveloppez un vieux back-end DataSnap ou RemObjects derrière une surface OpenAPI propre sans réécrire la logique métier.

BFF (Backend-for-Frontend)

Agrégez deux ou trois APIs upstream derrière une seule spec côté consommateur — votre SPA ou app mobile parle à un unique endpoint typé.

Mieux ensemble