Regrouper des schémas dans le parser OpenAPI

À partir de sgcOpenAPI 2024.9.0, le parser a été amélioré avec les nouvelles fonctionnalités suivantes :

- Bundle Specification : si la spécification est construite avec plusieurs schémas, le parser peut les regrouper dans un seul fichier de spécification.

- Output Parser Parameters : lors de la création de l'interface pascal, les paramètres utilisés pour importer les spécifications sont écrits dans l'en-tête du fichier pascal.

- Un nouvel événement a été créé pour le client sgcOpenAPI, OnBeforeRequest, qui peut être utilisé pour personnaliser la requête HTTP avant son envoi au serveur.

Bundle Specification

Lorsque les documents OpenAPI ou JSON Schema deviennent volumineux ou répétitifs, leur contenu peut être réparti dans plusieurs documents (sur le système de fichiers, des URL, en mémoire) et réunis via $ref. Ces descriptions d'API séparées peuvent ensuite être recomposées en un seul document, avec $ref pointant vers un emplacement interne au lieu d'un emplacement externe. C'est ce qu'on appelle le « bundling ».

Le parser sgcOpenAPI prend désormais en charge le bundling des spécifications OpenAPI. Cela se fait automatiquement lors de l'import d'un fichier.

Spécification OpenAPI éclatée

openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
paths:
  /things:
    get:
      responses: 
        '200':
          description: 'OK'
          content:
            application/json:
              schema:
                properties:
                  data:
                    type: array
                    items:
                      $ref: './schemas/thing.yaml'
  /things/{id}:
    get:
      parameters: 
        - name: id 
          in: path
          required: true
          schema: 
            type: string
            format: uuid
      responses: 
        '200':
          description: 'OK'
          content:
            application/json:
              schema:
                $ref: './schemas/thing.yaml'        

Spécification regroupée

openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
paths:
  /things:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/paths/~1things~1%7Bid%7D/get/responses/200/content/application~1json/schema'
  '/things/{id}':
    get:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  name:
                    type: string
                  type:
                    type: string
                    enum:
                      - type1
                      - type2 

Output Parser Parameters

 Le fichier pascal créé à partir de la spécification OpenAPI contient désormais les paramètres utilisés pour importer le fichier OpenAPI. Ces paramètres sont insérés sous forme de commentaires en haut du fichier Delphi.

{ ***************************************************************************  
  sgcOpenAPI component                                                         
  written by eSeGeCe                                                           
  copyright © 2024                                                             
  Email : info@esegece.com
  Web : http://www.esegece.com                                                 
  Source: D:\Downloads\ICAR-ADE-1\url-schemes\registrationURLScheme.json
  Parsed At: 2024-10-02 10:12:18
  Options: [Generate Classes] [Enable Classes] [Documentation]
  Authentication: Token
  Method Name: OperationId
  Base URL: https://spec.openapi.com
  *************************************************************************** } 

Événement OnBeforeRequest

Cet événement est appelé avant que la requête HTTP ne soit émise. Il permet de personnaliser les noms de paramètres, les en-têtes, la sécurité... Tu trouveras ci-dessous un exemple montrant comment remplacer le nom de certains paramètres.

procedure OnBeforeRequestEvent(Sender: TObject; const aRequest: TsgcOpenAPIRequest);
var
  i: Integer;
  oParameter: TsgcOpenAPIParameter;
begin
  for i := 0 to aRequest.Parameters.Count - 1 do
  begin
    oParameter := aRequest.Parameters[i];
    if oParameter._Name = 'meta-modified-from' then
      oParameter._name := 'eventDateTime-from';
    if oParameter._Name = 'meta-modified-to' then
      oParameter._name := 'eventDateTime-to';
  end;
end;