OpenAPI

경로, 작업 식별자, 참조는 그대로 유지하면서 OpenAPI 3.x YAML의 설명 필드를 번역합니다.

OpenAPI 문서에는 기계가 읽을 수 있는 API 계약과 사용자를 위한 설명이 함께 담겨 있습니다. yaml-openapi 파일 핸들러는 OpenAPI 3.x YAML에서 각 필드의 위치를 기준으로 title, description, summary 필드를 선택합니다. 경로, 작업 식별자, 참조는 그대로 유지됩니다.

API 계약을 일관되게 유지하기 #

다음 예시에서는 작업의 식별 정보는 그대로 유지하면서 설명만 다른 언어로 바꿀 수 있습니다:

yaml
openapi: 3.0.3
info:
  title: Order service
  version: 1.0.0
paths:
  /orders:
    get:
      operationId: listOrders
      summary: List your orders
      responses:
        "200":
          description: Orders retrieved

핸들러는 제목, 요약, 응답 설명을 선택합니다. /orders, listOrders, 1.0.0는 변경되지 않습니다. 정보 필드, 태그와 외부 문서의 설명, 경로 설명, 핸들러가 인식하는 스키마 및 작업 컨테이너 안의 설명 필드도 선택 대상입니다.

이 컨테이너들에서는 객체 형태의 예시와 기본값을 확인하세요. 이름이 title, description, summary인 중첩 속성은 예시 페이로드 데이터에 해당하더라도 선택될 수 있습니다. 일반적인 열거형 문자열과 $ref 값 등 다른 스키마 값은 변경되지 않습니다.

파서가 처리하려면 YAML 매핑의 openapi 버전이 3.로 시작해야 합니다. Swagger 2.x, 버전이 없는 문서, 그 밖의 버전은 거부됩니다. OpenAPI가 JSON을 허용하더라도 JSON 형식의 OpenAPI 파일이 선택되는 것은 아닙니다. 이 핸들러는 YAML을 처리하도록 정의되어 있습니다.

재구성과 재사용 #

명세 트리의 기준은 현재 원본입니다. 기존 문구는 설명 필드의 식별 정보와 출현 순서를 기준으로 대응시키며, 작업 식별 정보도 대응 관계를 찾는 데 활용합니다. 원본 설명이 바뀌면 새로 번역해야 하지만, 변경 없이 일치하는 필드는 기존 번역 문구를 재사용할 수 있습니다.

YAML 직렬화기는 문서를 재구성하는 과정에서 서식을 정규화할 수 있습니다. 이전 원본 명세와 번역 명세의 대응 관계를 유지하고, 필드 이동이나 반복되는 설명이 재사용에 영향을 주는지 확인하세요.

명세 핸들러 선택하기 #

CLI 파일 설정에서 .yaml 또는 .yml의 핸들러로 yaml-openapi를 명시적으로 선택하세요. 확장자만으로는 API 명세와 애플리케이션 카탈로그를 구분할 수 없습니다. 일반 YAML 핸들러는 훨씬 더 많은 문자열을 선택하며, 로캘 루트 YAML 핸들러는 다른 래퍼 규약을 따릅니다.

파일 선택과 대상 경로 설정에는 CLI 설정 또는 GitHub를 사용하세요. OpenAPI에서는 CLI로 키 범위를 지정해 번역할 수 없습니다.

계약 검증하고 설명 읽어 보기 #

사용 중인 OpenAPI 도구로 재구성된 문서를 검증하고, 경로, 작업 식별자, 참조, 필수 필드, 스키마 값을 원본과 비교하세요. 그런 다음 렌더링된 설명을 해당 계약과 함께 읽어 보세요. 응답 설명의 조건이나 보장 사항이 달라지면 명세 자체는 유효하더라도 개발자에게 오해를 줄 수 있습니다.