APIGit, the Git platform for API management | OpenAPI를 사용하여 재사용 가능한 구성 요소 정의

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string

매개변수

매개변수는 경로의 ID 또는 페이지 매김에 대한 제한 및 오프셋과 같은 여러 작업에서 재사용할 수 있습니다.

예:

components:
  parameters:
    userId:
      name: userId
      in: path
      required: true
      schema:
        type: integer
    limitParam:
      name: limit
      in: query
      schema:
        type: integer
        default: 10

응답

특히 오류 처리를 위한 공통 응답 구조는 한 번 정의하고 재사용하여 일관된 API 동작을 보장할 수 있습니다. 예:

components:
  responses:
    NotFound:
      description: The specified resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

헤더

여러 엔드포인트에서 사용할 수 있는 표준 헤더는 한 번 정의하고 재사용할 수 있습니다.

예:

components:
  headers:
    X-Rate-Limit:
      description: The number of allowed requests in the current period
      schema:
        type: integer

보안 계획

공통 보안 체계를 정의하면 이를 API 전체에서 재사용할 수 있어 일관된 보안 관행을 보장할 수 있습니다.

예:

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

재사용성을 위한 모범 사례

명명 규칙

구성요소에 대해 명확하고 설명이 포함된 이름을 사용하면 개발자가 구성요소를 더 쉽게 이해하고 재사용할 수 있습니다. 예를 들어 사용자 개체 스키마의 경우 User이고 일반적인 404 오류 응답의 경우 NotFound입니다.

조직과 구조

구성요소를 유형(예: 응답, 매개변수) 또는 도메인 영역(예: 인증, 사용자, 제품)별로 분류하여 논리적으로 구성합니다.

과도한 모듈화 방지

재사용성이 핵심이지만 너무 세분화하면 API 사양을 이해하고 유지 관리하는 것이 복잡해질 수 있습니다. 균형이 중요합니다.

예시 시나리오

일반적인 오류 응답 스키마

components:
  schemas:
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string

페이지 매김을 위한 쿼리 매개변수 재사용

paths:
  /users:
    get:
      parameters:
        - $ref: '#/components/parameters/limitParam'
        - name: offset
          in: query
          schema:
            type: integer
            default: 0

공유 인증 헤더

paths:
  /protected/resource:
    get:
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Success

결론

효과적으로 사용하기components OAS의 개체는 API 사양의 일관성과 유지 관리성을 크게 향상시킬 수 있습니다. 모범 사례를 준수하고 APIGIT의 직관적인 API 편집기를 활용함으로써 개발자는 효율적이고 재사용 가능하며 잘 구성된 API 정의를 만들 수 있습니다.