Parser OpenAPI: Agrupamento de Schemas

A partir do sgcOpenAPI 2024.9.0, o parser foi aprimorado com os seguintes novos recursos:

- Bundle Specification: se a especificação é construída com múltiplos esquemas, o parser pode agrupá-los em um único arquivo de especificação.

- Output Parser Parameters: ao criar a interface pascal, os parâmetros usados para importar as especificações são escritos no cabeçalho do arquivo pascal.

- Um novo evento foi criado para o sgcOpenAPI Client, OnBeforeRequest, que pode ser usado para personalizar a requisição HTTP antes de ser enviada ao servidor.

Agrupar Especificação

Quando documentos OpenAPI ou JSON Schema ficam muito grandes ou repetitivos, o conteúdo pode ser dividido em múltiplos documentos (no sistema de arquivos, URLs, na memória) e unidos por $ref. Essas descrições de API divididas podem então ser reunidas em um único documento, com $ref apontando para uma localização interna em vez de uma localização externa. Isso é chamado de "bundling".

Agora o sgcOpenAPI Parser suporta bundling de especificações openAPI. Isso é feito automaticamente ao importar um arquivo.

Especificação OpenAPI Dividida

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'        

Especificação Agrupada

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 

Parâmetros de Saída do Parser

 O arquivo pascal criado a partir da especificação openAPI agora contém os parâmetros usados para importar o arquivo openAPI. Esses parâmetros são criados como comentários no topo do arquivo 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
  *************************************************************************** } 

Evento OnBeforeRequest

Este evento é chamado antes de a requisição HTTP ser executada. Permite personalizar os nomes dos parâmetros, headers, segurança... Veja abaixo um exemplo de como substituir o nome de alguns parâmetros.

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;