sgcOpenAPI vs Swagger Codegen — Générer des clients Delphi plus vite

· Critiques

Le problème : la plupart des API modernes livrent une spec OpenAPI, pas un SDK Delphi

Si vous avez déjà intégré une API REST moderne en Delphi, le workflow ressemblait probablement à ceci : lire la doc, écrire à la main un wrapper autour de TIdHTTP ou TNetHTTPClient, coller les corps de requête dans des littéraux chaîne, parser les réponses avec TJSONObject, lutter avec la sérialisation TDateTime, répéter pour chaque endpoint. Ça marche mais ça ne passe pas à l'échelle. L'API a 80 endpoints, vous en wrappez 8, le fournisseur en ajoute 10 le mois prochain, et votre wrapper pourrit.

La promesse d'OpenAPI (anciennement Swagger) est que le fournisseur publie une description lisible par machine — un fichier YAML ou JSON — et un générateur la transforme en client typé dans le langage de votre choix. Pour la plupart des langages cela fonctionne extrêmement bien : openapi-generator et swagger-codegen produisent des clients idiomatiques pour Python, TypeScript, Go, Java, C#, Rust et beaucoup d'autres.

Pour Delphi l'histoire a historiquement été moins fluide. Ce billet compare les deux principales options en 2026 — le générateur Delphi open source historique swagger-codegen et le sgcOpenAPI natif commercial d'eSeGeCe — et montre ce que chacun produit à partir de la même spec d'entrée.

À propos de swagger-codegen et openapi-generator

Le projet Swagger, maintenant sous l'ombrelle SmartBear, livre swagger-codegen. Après un fork communautaire en 2018, un projet parallèle, openapi-generator, est devenu le standard de facto pour beaucoup de langages. Les deux outils supportent une longue liste de langages cibles via des templates Mustache. Un générateur Delphi (delphi dans swagger-codegen, plus des templates communautaires) existe, mais il a toujours été une cible de second rang maintenue par des bénévoles occasionnels.

À la date de rédaction, le template Delphi dans openapi-generator génère du code qui compile sur les vieilles versions de Delphi mais a des problèmes connus sur Delphi moderne (D11/D12/D13) : gestion incorrecte des champs nullable, manque de gardes {$IFDEF} pour la RTL plus récente, pas de support OpenAPI 3.1, pas de support de réponses en streaming, et un runtime qui dépend d'une version particulière de bibliothèque cliente HTTP. Plusieurs des issues GitHub de longue date contre le générateur Delphi sont ouvertes depuis des années. Votre kilométrage variera selon la spec.

À propos de sgcOpenAPI

sgcOpenAPI est un outil Delphi natif d'eSeGeCe. Il parse les spécifications OpenAPI 3.0 (et maintenant 3.1) et émet des unités Delphi qui suivent les conventions de nommage sgc : Tsgc[Api]Client pour le client, Tsgc[Api]_[Model] pour chaque objet de schéma, et une méthode par opération. Le code généré utilise TsgcHTTPComponentClient de sgcWebSockets comme transport, l'authentification, les retries, TLS et HTTP/2 sont donc hérités gratuitement.

Parce que le générateur est lui-même écrit en Delphi, il peut être embarqué dans un outil Delphi, exécuté depuis la ligne de commande, ou invoqué depuis un script de build. La sortie est constituée de fichiers .pas ordinaires sans dépendance runtime au-delà de sgcWebSockets — pas de JVM, pas de Node, pas de Python, pas de moteur de templates.

Comparaison fonctionnelle

Fonctionnalitéswagger-codegen / openapi-generator (cible Delphi)sgcOpenAPI
OpenAPI 2.0 (Swagger)OuiOui
OpenAPI 3.0Oui (openapi-generator)Oui
OpenAPI 3.1Limité à la date de rédactionOui
Prérequis runtimeJava 11+ pour exécuter le générateurAucun (exe Delphi natif)
Versions Delphi cibléesMeilleur effort sur D10.x, souvent cassé sur D11+ à la date de rédactionD7 à D13
Backend HTTPIndy par défaut dans les templates Delphi actuelssgcHTTPComponentClient (Indy / ICS / SChannel, plus HTTP/2)
Réponses async / streamingLimitéOui
Auth OAuth2 / API key / bearerPartielOui, composants natifs
Polymorphisme (oneOf, allOf, discriminator)LimitéOui
Champs nullableIncohérentOui (TsgcNullable<T>)
Upload de fichiers / multipartPartielOui
Génération de stubs serveurOui (autres langages surtout)Oui (stubs serveur Delphi avec sgcWebSocketHTTPServer)
LicenceOpen source (Apache 2.0)Commercial

Comparaison des workflows

Workflow swagger-codegen

  1. Installer Java 11 ou plus récent.
  2. Télécharger le JAR openapi-generator-cli.
  3. Exécuter java -jar openapi-generator-cli.jar generate -i spec.yaml -g delphi -o ./out.
  4. Ouvrir les fichiers .pas générés dans votre IDE. Ajouter le chemin runtime Indy. Corriger les problèmes de compilation pour votre version Delphi. Patcher la gestion des nullable. Relancer après chaque changement de spec.
  5. Le client généré dépend d'une unité de support runtime séparée livrée par le template. Vous livrez cette unité avec votre projet.

Workflow sgcOpenAPI

  1. Ouvrir l'IDE sgcOpenAPI ou appeler la CLI : sgcOpenAPI.exe -i spec.yaml -o ./out.
  2. Ouvrir l'unité générée dans l'IDE. Elle utilise TsgcHTTPComponentClient que vous avez déjà si vous utilisez sgcWebSockets.
  3. Déposer le composant client généré sur une fiche, définir l'URL de base et les identifiants, et appeler les méthodes typées.

Côte à côte : une méthode GET /users/{id} générée

Même fragment OpenAPI, les deux outils, opération identique. Les noms des helpers et le formatage exact sont légèrement stylisés pour la clarté mais les différences d'approche sont réelles.

swagger-codegen (cible Delphi, simplifié)

function TUsersApi.GetUserById(const Id: Int64): TUser;
var
  HttpRequest: TIdHTTP;
  Path, Response: string;
  JsonValue: TJSONValue;
begin
  Path := StringReplace(BasePath + '/users/{id}', '{id}', IntToStr(Id), [rfReplaceAll]);
  HttpRequest := TIdHTTP.Create(nil);
  try
    HttpRequest.Request.CustomHeaders.AddValue('Authorization', 'Bearer ' + FApiKey);
    Response := HttpRequest.Get(Path);
  finally
    HttpRequest.Free;
  end;
  JsonValue := TJSONObject.ParseJSONValue(Response);
  try
    Result := TUser.Create;
    Result.Id := (JsonValue as TJSONObject).GetValue<Int64>('id');
    Result.Name := (JsonValue as TJSONObject).GetValue<string>('name');
    // ... nullable fields handled inconsistently ...
  finally
    JsonValue.Free;
  end;
end;

sgcOpenAPI

function TsgcUsersApiClient.GetUserById(const aId: Int64): TsgcUser;
var
  vResponse: TsgcAPIResponse;
begin
  Result := nil;
  vResponse := DoGet(Format('/users/%d', [aId]));
  Try
    if vResponse.StatusCode = 200 then
      Result := TsgcUser.FromJSON(vResponse.Content);
  Finally
    vResponse.Free;
  End;
end;

// TsgcUser is generated with typed nullable fields:
//   property Id: Int64 read FId write FId;
//   property Name: string read FName write FName;
//   property Email: TsgcNullable<string> read FEmail write FEmail;
//   property CreatedAt: TDateTime read FCreatedAt write FCreatedAt;
//
// Authentication, retry, HTTP/2, TLS are configured on the
// underlying TsgcHTTPComponentClient once, not per-method.

Différences à souligner :

Stubs serveur

Les deux outils peuvent aussi générer du code côté serveur, mais les templates serveur Delphi dans openapi-generator sont minimes à la date de rédaction. sgcOpenAPI génère un handler basé sur TsgcWebSocketHTTPServer avec une méthode virtuelle par opération, validation des requêtes, mise en forme des réponses et un endpoint explorateur OpenAPI intégré. Pour les services internes où vous voulez qu'un seul projet Delphi expose l'API et qu'un client Delphi la consomme, l'aller-retour est très court.

Quand swagger-codegen reste le bon choix

Quand sgcOpenAPI fait gagner du temps réel

Pour conclure

La génération de code à partir d'OpenAPI est un de ces gains de productivité qui se cumulent sur la durée de vie d'un projet — à condition que le générateur suive le rythme de la spec et de votre version Delphi. swagger-codegen / openapi-generator sont d'excellents outils multi-langages, mais leur cible Delphi a historiquement été traitée comme un meilleur effort. sgcOpenAPI est une alternative native Delphi ciblée qui livre des clients OpenAPI 3.0 / 3.1 compilables, idiomatiques et complets (et des stubs serveur) sans dépendance Java et sans le cycle de patches manuels. Pour la plupart des équipes Delphi qui intègrent déjà des API REST, il s'amortit la première fois qu'un fournisseur met à jour sa spec.