OpenAPI Parser 스키마 번들링

sgcOpenAPI 2024.9.0부터 파서가 다음 새 기능으로 개선됐어요:

- 번들 사양: 사양이 여러 스키마로 구성된 경우, 파서가 단일 사양 파일로 번들할 수 있어요.

- 출력 파서 매개변수: Pascal 인터페이스를 생성할 때, 사양을 가져오는 데 사용된 매개변수가 Pascal 파일의 헤더에 기록돼요.

- sgcOpenAPI 클라이언트에 새 이벤트 OnBeforeRequest가 생성됐어요. HTTP 요청을 서버로 보내기 전에 맞춤 설정하는 데 사용할 수 있어요.

번들 사양

OpenAPI나 JSON Schema 문서가 방대해지거나 반복적이 되면, 내용을 여러 문서(파일 시스템, URL, 메모리 어딘가)로 분할하고 $ref로 결합할 수 있어요. 이렇게 분할된 API 설명은 외부 위치 대신 내부 위치를 가리키는 $ref를 사용해 하나의 문서로 다시 결합할 수 있어요. 이를 "번들링"이라고 해요.

이제 sgcOpenAPI Parser는 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;