OpenAPI 解析器 Bundle Schemas

从 sgcOpenAPI 2024.9.0 起，解析器新增了以下功能：

- Bundle 规范：如果规范由多个模式构建，解析器可以将其合并为单一规范文件。

- 输出解析器参数：创建 Pascal 接口时，用于导入规范的参数会写入 Pascal 文件的头部。

- 为 sgcOpenAPI 客户端创建了新事件 OnBeforeRequest，可用于在请求发送到服务器之前自定义 HTTP 请求。

Bundle 规范

当 OpenAPI 或 JSON Schema 文档变得庞大或重复时，内容可以拆分到多个文档（文件系统、URL、内存中）并通过 $ref 连接。这些拆分的 API 描述随后可以重新合并为一个文档，其中 $ref 指向内部位置而非外部位置。这称为"bundling（捆绑）"。

现在，sgcOpenAPI 解析器支持捆绑 OpenAPI 规范。导入文件时会自动完成此操作。

拆分的 OpenAPI 规范

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'        

捆绑后的规范

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 

输出解析器参数

从 OpenAPI 规范创建的 Pascal 文件现在包含用于导入 OpenAPI 文件的参数。这些参数作为注释写在 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
  *************************************************************************** } 

OnBeforeRequest 事件

此事件在 HTTP 请求发送之前调用。可用于自定义参数名称、请求头、安全性等。以下示例展示如何替换某些参数的名称。

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;