liminfo

OpenAPI Reference

OpenAPI/Swagger 스펙 레퍼런스

26개 결과

OpenAPI Reference 소개

OpenAPI 레퍼런스는 REST API를 기술하는 데 사용되는 OpenAPI 3.0 명세 전체 구조를 다룹니다. HTTP 메서드 오퍼레이션(GET, POST, PUT, DELETE)이 포함된 경로 정의, 요청 본문 및 응답 스키마, 경로·쿼리 파라미터, Bearer JWT·API Key·OAuth2 인증 코드 플로우를 포함한 보안 스킴 등 주요 섹션마다 구문과 실제 예제를 제공합니다.

이 레퍼런스는 API 계약을 작성하는 백엔드 개발자, REST API와 통합하는 프론트엔드 엔지니어, API 게이트웨이를 관리하는 DevOps 팀에 특히 유용합니다. 경로, 스키마, 파라미터, 응답, 인증, 컴포넌트 등 6개 카테고리로 구성되어 실제 OpenAPI YAML 문서 구조를 그대로 반영하므로 작업 흐름을 끊지 않고 원하는 내용을 바로 찾을 수 있습니다.

컴포넌트 섹션에서는 $ref 참조, allOf/oneOf/anyOf 스키마 조합, 다형성 모델을 위한 discriminator, 재사용 가능한 파라미터 및 응답 정의 등 고급 재사용 패턴을 다룹니다. 모든 항목에는 API 명세에 바로 복사해 사용할 수 있는 완전한 YAML 예제가 포함되어 있습니다.

주요 기능

  • operationId와 태그를 포함한 GET, POST, PUT, DELETE 경로 아이템 전체 커버리지
  • type, format, enum, required 필드와 배열/객체 조합을 사용한 스키마 정의
  • 다형성 타입을 위한 allOf, oneOf, anyOf 스키마 조합 및 discriminator
  • 컴포넌트 전체에서 스키마, 파라미터, 응답을 연결하는 $ref 참조
  • required 플래그와 format 어노테이션을 포함한 경로, 쿼리, 헤더 파라미터 정의
  • HTTP 상태 코드, 콘텐츠 타입, 응답 헤더, HATEOAS 링크를 포함한 응답 정의
  • Bearer JWT, API Key(헤더/쿼리), OAuth2 인증 코드 플로우 보안 스킴
  • 재사용 가능한 components/parameters, components/responses, components/requestBodies 패턴

자주 묻는 질문

OpenAPI 3.0이란 무엇이며 Swagger 2.0과 어떻게 다른가요?

OpenAPI 3.0은 Swagger 2.0의 후속 버전으로, 재사용 가능한 정의를 위한 통합 `components` 섹션, 여러 서버 URL 지원, `body` 파라미터를 대체하는 풍부한 `requestBody` 필드, 개선된 보안 스킴 정의(OAuth2 플로우 포함)를 도입했습니다. 루트 키가 `swagger`에서 `openapi`로 변경되었습니다.

OpenAPI에서 재사용 가능한 스키마 컴포넌트를 어떻게 정의하나요?

`components/schemas` 아래에 스키마를 정의하고 `$ref: "#/components/schemas/스키마명"`으로 참조합니다. 이를 통해 여러 요청 본문과 응답에서 정의를 복사하지 않고 동일한 스키마를 사용할 수 있습니다. 같은 패턴이 파라미터, 응답, 요청 본문에도 각각의 `components` 하위 키로 적용됩니다.

allOf, oneOf, anyOf의 차이점은 무엇인가요?

`allOf`는 나열된 모든 스키마에 대해 유효해야 합니다(상속에 사용). `oneOf`는 정확히 하나의 스키마에만 유효해야 합니다(상호 배타적 변형). `anyOf`는 하나 이상의 스키마에 유효하면 됩니다(유니온 타입). `oneOf`와 함께 `discriminator`를 사용하면 속성 값을 기반으로 클라이언트가 어떤 하위 스키마를 사용할지 알 수 있습니다.

OpenAPI 명세에 Bearer JWT 인증을 어떻게 추가하나요?

`components/securitySchemes`에 `type: http`, `scheme: bearer`, 선택적으로 `bearerFormat: JWT`로 보안 스킴을 정의합니다. 그런 다음 최상위 `security` 배열로 전역 적용하거나 오퍼레이션별로 적용합니다. 특정 엔드포인트를 공개로 표시하려면 해당 오퍼레이션에 `security: []`를 설정해 전역 기본값을 재정의합니다.

OpenAPI에서 경로 파라미터를 어떻게 문서화하나요?

경로 파라미터는 경로 문자열(예: `/users/{id}`)과 `parameters` 배열 모두에 선언되며, `in: path`, `required: true`, 그리고 `schema` 정의가 포함됩니다. 중괄호 안의 파라미터 이름은 파라미터 객체의 `name` 필드와 정확히 일치해야 합니다.

요청 및 응답 본문에 예제를 정의할 수 있나요?

네. 스키마 정의 안에 직접 `example` 필드를 추가하거나, `content` 미디어 타입 객체 안의 `examples` 맵을 사용해 여러 명명된 예제를 제공할 수 있습니다. `examples` 맵 방식을 사용하면 요약과 설명이 포함된 다양한 시나리오(예: 관리자 사용자 vs. 일반 사용자 응답)를 보여줄 수 있습니다.

HATEOAS란 무엇이며 OpenAPI에서 링크는 어떻게 정의하나요?

HATEOAS(Hypermedia As The Engine Of Application State)는 응답에 관련 오퍼레이션에 대한 링크가 포함되는 REST 패턴입니다. OpenAPI 3.0에서 응답 `links`를 통해 POST 응답의 `id`를 이후 GET 오퍼레이션의 `id` 파라미터로 사용할 수 있음을 선언하여 API 호출 간의 관계를 문서화할 수 있습니다.

OpenAPI 레퍼런스를 효과적으로 사용하는 방법은?

카테고리 필터를 사용해 필요한 섹션(경로, 스키마, 파라미터, 응답, 인증, 컴포넌트)으로 이동하세요. 각 항목에는 구문 키워드, 평이한 설명, 완전한 YAML 예제가 표시됩니다. 키워드(예: "oauth2", "array", "required")로 검색하면 특정 구문을 즉시 찾을 수 있습니다.