Link를 번역했습니다 (2020-11-15)

Components Section

종종 여러 API 작업은 몇 가지 공통 매개 변수가 있거나 동일한 응답 구조를 반환합니다. 코드 중복을 방지하기 위해 전역 구성 요소 섹션에 공통 정의를 배치하고 $ref를 사용하여 참조할 수 있습니다. 아래 예에서 User 객체의 중복 정의는 단일 구성 요소와 해당 구성 요소에 대한 참조로 대체됩니다.

Before:

paths:
  /users/{userId}:
    get:
      summary: Get a user by ID
      parameters:
        ...
      responses:
        '200':
          description: A single user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string
  /users:
    get:
      summary: Get all users
      responses:
        '200':
          description: A list of users.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string

After:

paths:
  /users/{userId}:
    get:
      summary: Get a user by ID
      parameters:
        ...
      responses:
        '200':
          description: A single user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /users:
    get:
      summary: Get all users
      responses:
        '200':
          description: A list of users.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

Components structure

components는 schemas(데이터 모델), parameters, responses, examples 등 다양한 재사용 가능한 정의를 위한 컨테이너 역할을 합니다. components의 정의는 components 외부에서 명시적으로 참조하지 않는 한 API에 직접적인 영향을 주지 않습니다. 즉, components는 모든 작업에 적용되는 매개 변수 및 응답이 아닙니다. 다른 곳에서 참조 할 정보의 일부일 뿐입니다. components에서 정의는 shemas, parameters 등 유형별로 그룹화됩니다. 다음 예는 사용 가능한 하위 섹션을 나열합니다. 모든 하위 섹션은 선택 사항입니다.

components:
  # Reusable schemas (data models)
  schemas:
    ...
  # Reusable path, query, header and cookie parameters
  parameters:
    ...
  # Security scheme definitions (see Authentication)
  securitySchemes:
    ...
  # Reusable request bodies
  requestBodies:
    ...
  # Reusable responses, such as 401 Unauthorized or 400 Bad Request
  responses:
    ...
  # Reusable response headers
  headers:
    ...
  # Reusable examples
  examples:
    ...
  # Reusable links
  links:
    ...
  # Reusable callbacks
  callbacks:
    ...

각 하위 섹션에는 하나 이상의 명명된 components(definitions)가 포함됩니다.

바로 상위 문장의 components는 뜻 그대로 components > 하위 섹션 > component(구성요소) 를 가리킵니다.

components:
  schemas:
    User:
      type: object
      ...
    Pet:
      type: object
      ...

component의 이름은 다음 문자로만 구성 될 수 있습니다.

A..Z a..z 0..9 . _ -

example)
User
New_User
org.example.User
401-Unauthorized

component의 이름은 API 사양의 다른 부분에서 $ref를 통해 component를 참조하는 데 사용됩니다.

$ref: '#/components/<type>/<name>'

example)
$ref: '#/components/schemas/User'

이름으로 직접 참조되는 securitySchemes의 정의는 예외입니다. (Authentication 참조)

Components Example

다음은 재사용 가능한 data schemas, parameters 및 responses을 포함하는 components의 예입니다. 다른 구성 요소 유형 (links, example 및 기타)도 유사하게 정의됩니다.

components:
  #-------------------------------
  # Reusable schemas (data models)
  #-------------------------------
  schemas:
    User:             # Can be referenced as '#/components/schemas/User'
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
    Error:            # Can be referenced as '#/components/schemas/Error'
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
  #-------------------------------
  # Reusable operation parameters
  #-------------------------------
  parameters:
    offsetParam:      # Can be referenced via '#/components/parameters/offsetParam'
      name: offset
      in: query
      description: Number of items to skip before returning the results.
      required: false
      schema:
        type: integer
        format: int32
        minimum: 0
        default: 0
    limitParam:       # Can be referenced as '#/components/parameters/limitParam'
      name: limit
      in: query
      description: Maximum number of items to return.
      required: false
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 100
        default: 20
  #-------------------------------
  # Reusable responses
  #-------------------------------
  responses:
    404NotFound:       # Can be referenced as '#/components/responses/404NotFound'
      description: The specified resource was not found.
    ImageResponse:     # Can be referenced as '#/components/responses/ImageResponse'
      description: An image.
      content:
        image/*:
          schema:
            type: string
            format: binary
    GenericError:      # Can be referenced as '#/components/responses/GenericError'
      description: An error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

Externally Defined Components

components의 개별 정의는 인라인 (이전 예제에서와 같이) 또는 외부 정의에 대한 $ref 참조를 사용하여 지정할 수 있습니다.

components:
  schemas:
    Pet:
      $ref: '../models/pet.yaml'
      # Can now use use '#/components/schemas/Pet' instead
    User:
      $ref: 'https://api.example.com/v2/openapi.yaml#/components/schemas/User'
      # Can now use '#/components/schemas/User' instead
  responses:
    GenericError:
      $ref: '../template-api.yaml#/components/responses/GenericError'
      # Can now use '#/components/responses/GenericError' instead

이렇게하면 모든 참조에서 외부 파일 경로를 반복하는 대신 사용할 수 있는 외부 정의에 대한 로컬 "별칭(alias)"을 정의 할 수 있습니다. 참조된 파일의 위치가 변경되면 모든 참조가 아닌 한 곳 (구성 요소)에서만 변경하면됩니다.

Differences From OpenAPI 2.0

OpenAPI 2.0에는 재사용 가능한 구성 요소 (정의, 매개 변수, 응답 및 securityDefinitions)에 대한 별도의 섹션이 있습니다. OpenAPI 3.0에서는 모두 구성 요소 내부로 이동되었습니다. 또한 정의는 스키마로 이름이 바뀌었고 securityDefinitions는 securitySchemes로 이름이 바뀌 었습니다 (다른 철자: schemAs vs securitySchemEs에 유의하십시오). 참조는 새로운 구조를 반영하도록 변경됩니다.

OpenAPI 2.0                    OpenAPI 3.0
'#/definitions/User'         → '#/components/schemas/User'
'#/parameters/offsetParam'   → '#/components/parameters/offsetParam'
'#/responses/ErrorResponse'  → '#/components/responses/ErrorResponse'

Reference

Component Object