$ref를 사용하여 OpenAPI 파일에서 코드 단편 재사용

온라인에서 편집하기

개발자 툴킷 명령행을 사용하여 IBM® API Connect 관리 서버에 API를 배치하는 경우 OpenAPI YAML및 JSON API 정의 파일의 $ref 필드를 사용하여 별도의 파일에 정의된 OpenAPI 코드의 단편을 참조할 수 있습니다. API Connect 가 소스 API 정의 파일을 처리할 때 $ref 필드가 대상 파일의 컨텐츠로 대체됩니다.

소스 YAML 파일에서 다음 구문을 사용하십시오.

$ref: path_to_file_containing_code_fragment

소스 JSON 파일에서 다음 구문을 사용하십시오.

{  
$ref: path_to_file_containing_code_fragment
}

예를 들어,

$ref: code_fragments/my_fragment.yaml

{
  "$ref": "code_fragments/my_fragment.json"
}

소스 API 정의 파일에 정의된 API에서 다음 조치를 수행할 때 $ref 필드가 대상 코드 단편으로 대체됩니다.

apic publish 명령을 사용하여 API Connect 관리 서버에 API를 스테이징하거나 공개하십시오. 자세한 내용은 ‘API 및 애플리케이션 게시 ’를 참조하세요.
apic validate 명령을 사용하여 API 정의 YAML 파일의 유효성을 검증합니다. 자세한 내용은 API 또는 제품의 YAML 또는 JSON 정의 검증하기를 참조하세요.

중요: OpenAPI 파일의 루트 레벨에서 $ref 필드를 삽입할 수 없습니다.

예제 1

소스 YAML 파일에는 다음 OpenAPI 코드가 포함되어 있습니다.

swagger: '2.0'
info:
  version: 1.0.0
  title: Branches
  x-ibm-name: Branches
  description: Provides operations relating to BankA branch information.
basePath: /branches
paths:
  /details:
    get:
      responses:
        - $ref: code_fragments/paths.yaml#/details/get/responses
       .
       .
       .

paths.yaml 파일에는 다음 OpenAPI 코드 단편이 포함되어 있습니다.

details:
  get:
    responses:
      '200':
        description: 200 OK defined in $ref file
        schema:
          $ref: '#/definitions/branch'
    summary: Branch details
    description: Retrieve details of the current branches of BankA.

API Connect 가 소스 YAML 파일을 처리할 때 $ref 필드가 대상 코드 단편으로 대체되어 다음 OpenAPI 코드를 생성합니다.

swagger: '2.0'
info:
  version: 1.0.0
  title: Branches
  x-ibm-name: Branches
  description: Provides operations relating to BankA branch information.
basePath: /branches
paths:
  /details:
    get:
      responses:
        '200':
          description: 200 OK
          schema:
            $ref: '#/definitions/branch'
      summary: Branch details
      description: Retrieve details of the current branches of BankA.
       .
       .
       .

예제 2

매개변수 세부사항만 포함하는 외부 파일에 대한 참조 예제:

openapi: 3.0.0

info:
  version: 3.0.1
  title: BeamUp API
  x-ibm-name: BeamUpAPI
servers:
  - url: /
paths:
  /customers:
    get:
      parameters:
        - $ref: tests/fixtures/api/referenceFile.yaml
      responses:  
        200:
          description: An array of customers
          content:
            application/json:
              schema:
                type: object
                properties:
                  customerID:
                    type: string
                  customerName:
                    type: string
.
.
.

referenceFile.yaml 파일에는 다음 OpenAPI 코드 단편이 포함되어 있습니다.

name: page
in: query
description: page of results to return
required: true
schema:
  type: integer

경로 코드 단편 내에 매개변수를 포함하는 외부 파일에 대한 참조의 예:

openapi: 3.0.0

info:
  version: 3.0.1
  title: BeamUp API
  x-ibm-name: BeamUpAPI
servers:
  - url: /
paths:
  /customers:
    get:
      parameters:
        - $ref: tests/fixtures/api/referenceFileWithPath.yaml#/customers/get/parameters
      responses:  
        200:
          description: An array of customers
          content:
            application/json:
              schema:
                type: object
                properties:
                  customerID:
                    type: string
                  customerName:
                    type: string

referenceFileWithPath.yaml 파일에는 다음 OpenAPI 코드 단편이 포함되어 있습니다.

customers:
  get:
    parameters:
      name: page
      in: query
      description: page of results to return
      required: true
      schema:
        type: integer