Le Serveur sgcOpenAPI héberge un service HTTP dont le contrat est décrit par une spécification OpenAPI 3.0. Les routes sont construites automatiquement à partir de la section paths de la spécification, une Swagger UI est exposée prêt à l'emploi et les requêtes entrantes peuvent être validées par rapport aux JSON-Schemas déclarés par chaque opération. Deux composants sont fournis pour héberger le serveur :
Les deux composants partagent le même moteur, les mêmes options et les mêmes événements.
Serveur autonome défini dans l'unité sgcHTTPServer_OpenAPI. Configurez le port d'écoute, chargez une spécification OpenAPI et activez le serveur.
uses sgcHTTPServer_OpenAPI;
var
oServer: TsgcHTTPServer_OpenAPI;
begin
oServer := TsgcHTTPServer_OpenAPI.Create(nil);
oServer.Bindings.Add.Port := 8080;
oServer.OpenAPIOptions.Endpoint.ServeSwaggerUI := True;
oServer.LoadFromFile('petstore.json');
oServer.OnRequest := MyOnRequest;
oServer.Active := True;
end;
Compatible avec sgcWebSockets, défini dans l'unité sgcWebSocket_Server_API_OpenAPI. Affectez un TsgcWebSocketHTTPServer existant à la propriété Server afin qu'une seule instance de serveur puisse dispatcher à la fois les trames WebSocket et les requêtes HTTP OpenAPI. En interne, il délègue au même moteur que celui utilisé par le composant autonome, de sorte que la surface d'API est identique.
Le serveur sert automatiquement les points de terminaison suivants (chacun peut être désactivé via OpenAPIOptions.Endpoint) :
/openapi.json : retourne la spécification OpenAPI chargée, contrôlée par OpenAPIOptions.Endpoint.ServeSpec.
/docs : Swagger UI intégré pour parcourir et essayer l'API, contrôlé par OpenAPIOptions.Endpoint.ServeSwaggerUI.
OPTIONS * : réponses preflight CORS, envoyées lorsque OpenAPIOptions.CORS.Enabled est True.
Propriété de configuration de premier niveau, de type TsgcOpenAPIServer_Options. Regroupe trois sous-objets :
Endpoint : points de terminaison intégrés et chargement de la spécification.
BasePath : préfixe URL optionnel ajouté à chaque route déclarée dans la spécification.
SpecFile : si affecté, le fichier est chargé automatiquement lorsque le serveur devient Active.
ServeSpec : si True (par défaut), la spécification chargée est servie à /openapi.json.
ServeSwaggerUI : si True (par défaut), la Swagger UI est servie à /docs.
Validation : indicateurs de validation des requêtes, tous par défaut à False.
ValidateRequest : commutateur principal qui active la validation pour l'ensemble de la requête.
ValidateRequestBody : valide le corps de la requête par rapport au JSON-Schema déclaré dans la spécification.
ValidateQueryParams : valide les paramètres de requête par rapport à leur schéma déclaré.
ValidatePathParams : valide les paramètres de chemin par rapport à leur schéma déclaré.
ValidateRequired : rejette la requête lorsqu'un paramètre déclaré comme obligatoire est manquant.
CORS : prise en charge cross-origin.
Enabled : si True, les en-têtes CORS sont émis pour chaque réponse et les requêtes preflight OPTIONS reçoivent une réponse automatiquement.
AllowOrigins : valeur de Access-Control-Allow-Origin (par défaut *).
AllowHeaders : valeur de Access-Control-Allow-Headers (par défaut Content-Type, Authorization).
AllowMethods : valeur de Access-Control-Allow-Methods (par défaut GET, POST, PUT, DELETE, PATCH, OPTIONS).
Vous trouverez ci-dessous la liste des événements que vous pouvez gérer lors de l'utilisation du Serveur OpenAPI.
OnBeforeRequest : se déclenche avant que la requête ne soit dispatchée à OnRequest. Définissez le paramètre Accept sur False pour rejeter la requête avec une réponse 403.
OnRequest : gestionnaire principal. Inspectez aOperationId et utilisez aContext pour lire la requête et écrire la réponse. Définissez Handled sur True après avoir produit une réponse.
OnAfterRequest : se déclenche après le retour du gestionnaire utilisateur. Utile pour la journalisation ou les métriques.
OnAuthenticate : se déclenche avant le dispatch lorsque l'authentification est requise. Définissez Authenticated sur False pour rejeter avec une réponse 401.
OnValidationError : se déclenche lorsqu'une ou plusieurs règles de validation échouent. Inspectez aErrors et définissez Continue sur False pour rejeter la requête avec une réponse 400.
OnException : se déclenche lorsqu'une exception non gérée se propage depuis le gestionnaire utilisateur. Ajustez aResponseCode si le 500 par défaut doit être remplacé.
Le serveur prend en charge deux approches d'écriture :