OpenAPI v3.0(OAS 3.0)란? REST API 문서화를 위한 표준 명세 이해하기

5월 01, 2025


API를 개발하다 보면 “이 API는 어떤 엔드포인트를 제공하는지”, “요청 파라미터는 무엇인지”, “응답 데이터는 어떤 구조인지”, “인증은 어떻게 처리하는지”를 명확하게 문서화해야 합니다.

OpenAPI Specification(OAS) 은 이러한 API 정보를 표준 형식으로 정의하고 문서화하기 위한 명세입니다. 특히 OAS 3.0은 RESTful API를 포함한 HTTP 기반 API의 구조, 요청/응답 형식, 인증 방식, 서버 정보 등을 YAML 또는 JSON 형식으로 표현할 수 있게 해줍니다.

OpenAPI는 과거 Swagger Specification 으로 불리던 명세에서 출발했습니다. 이후 Swagger Specification이 OpenAPI Initiative로 이관되면서 현재는 OpenAPI Specification이라는 이름으로 관리되고 있습니다.

OpenAPI를 사용하는 이유

OpenAPI를 사용하면 API 문서를 단순한 설명 문서가 아니라, 사람이 읽고 도구가 처리할 수 있는 표준화된 계약서처럼 활용할 수 있습니다.

주요 장점은 다음과 같습니다.

1. 명확한 API 문서화

OpenAPI 문서에는 엔드포인트, HTTP 메서드, 요청 파라미터, 요청 본문, 응답 구조, 오류 응답, 인증 방식 등을 명확하게 기술할 수 있습니다.

이를 통해 백엔드 개발자, 프론트엔드 개발자, QA, 외부 API 사용자 모두가 동일한 기준으로 API를 이해할 수 있습니다.

2. 자동화 도구와의 연동

OpenAPI 문서는 다양한 도구와 연동할 수 있습니다.

예를 들어 다음과 같은 작업을 자동화하거나 반자동화할 수 있습니다.

  • API 문서 페이지 생성
  • 클라이언트 SDK 생성
  • 서버 코드 스텁 생성
  • Mock Server 생성
  • API 테스트
  • API 계약 검증
  • 요청/응답 스키마 검증

3. 팀 간 일관성 유지

여러 팀이 함께 API를 개발할 때 OpenAPI를 사용하면 API 설계와 문서화 기준을 통일할 수 있습니다.

특히 마이크로서비스 구조나 외부 공개 API를 운영하는 환경에서는 API 명세를 표준화하는 것이 유지보수성과 협업 효율을 높이는 데 큰 도움이 됩니다.

OpenAPI v3.0의 주요 구성 요소

OpenAPI 문서는 일반적으로 다음과 같은 최상위 요소로 구성됩니다.

openapi

사용 중인 OpenAPI 명세 버전을 나타냅니다.

예:

openapi: 3.0.0

info

API의 기본 정보를 정의합니다.

주로 다음 정보를 포함합니다.

  • API 제목
  • 설명
  • 버전
  • 라이선스
  • 연락처 정보

예:

info:
  title: Sample API
  description: 샘플 API 문서입니다.
  version: 1.0.0

servers

API 서버의 기본 URL을 정의합니다.

개발, 스테이징, 운영 환경을 구분해 여러 서버를 등록할 수 있습니다.

예:

servers:
  - url: https://api.example.com/v1
    description: Production server

paths

API의 실제 엔드포인트와 각 엔드포인트에서 지원하는 HTTP 메서드를 정의합니다.

예:

paths:
  /users:
    get:
      summary: 사용자 목록 조회
      responses:
        '200':
          description: 성공

components

여러 곳에서 재사용할 수 있는 스키마, 응답, 파라미터, 보안 스키마 등을 정의합니다.

예:

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

security

API 전체 또는 특정 작업에 적용할 보안 방식을 정의합니다.

예를 들어 API Key, Bearer Token, OAuth2 등의 인증 방식을 명세할 수 있습니다.

tags

API를 기능별로 그룹화할 때 사용합니다.

예를 들어 users, posts, auth 같은 태그를 사용하면 문서에서 API를 더 보기 좋게 분류할 수 있습니다.

externalDocs

API와 관련된 외부 문서 링크를 제공할 때 사용합니다.

예를 들어 별도의 개발자 가이드, 인증 가이드, 정책 문서 등을 연결할 수 있습니다.

OpenAPI v3.0 예제

아래 예제는 모두 YAML 형식으로 작성했습니다. OpenAPI 문서는 YAML뿐 아니라 JSON 형식으로도 작성할 수 있습니다.

예제 1: 가장 단순한 API 명세

openapi: 3.0.0
info:
  title: Simple API
  version: 1.0.0

servers:
  - url: https://api.example.com/v1

paths:
  /hello:
    get:
      summary: Greet the world
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                type: string

이 예제는 /hello 엔드포인트에 GET 요청을 보내면 문자열 응답을 반환하는 간단한 API를 정의합니다.

예제 2: Path Parameter와 응답 객체 사용

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0

servers:
  - url: https://api.example.com

paths:
  /users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          description: User ID
          schema:
            type: integer
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found

components:
  schemas:
    User:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: Hong Gil-dong

이 예제는 /users/{id} 형식의 경로 파라미터를 사용하는 API입니다.

id 값은 URL 경로에 포함되며, 응답은 components.schemas.User에 정의된 User 객체 구조를 따릅니다.

$ref를 사용하면 같은 데이터 모델을 여러 API에서 재사용할 수 있어 명세 중복을 줄일 수 있습니다.

예제 3: POST 메서드와 Request Body 사용

openapi: 3.0.0
info:
  title: Blog API
  version: 1.0.0

servers:
  - url: https://api.example.com

paths:
  /posts:
    post:
      summary: Create a new blog post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Post'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
        '400':
          description: Invalid request

components:
  schemas:
    Post:
      type: object
      required:
        - title
        - content
        - author
      properties:
        title:
          type: string
          example: OpenAPI 시작하기
        content:
          type: string
          example: OpenAPI v3.0의 기본 구조를 설명합니다.
        author:
          type: string
          example: admin

이 예제는 블로그 게시글을 생성하는 POST /posts API입니다.

requestBody를 통해 클라이언트가 서버로 전달해야 하는 JSON 요청 본문 구조를 정의하고, responses에서는 생성 성공 시 반환되는 응답 구조를 정의합니다.

OpenAPI 작성 시 알아두면 좋은 점

1. YAML과 JSON 모두 사용 가능

OpenAPI 문서는 YAML과 JSON 형식을 모두 지원합니다.

실무에서는 사람이 읽고 작성하기 쉬운 YAML을 많이 사용하지만, 자동화 도구나 일부 시스템에서는 JSON 형식을 사용하기도 합니다.

2. 공통 모델은 components에 분리하기

여러 API에서 반복되는 요청/응답 모델은 components.schemas에 정의하고 $ref로 참조하는 것이 좋습니다.

이렇게 하면 명세의 중복을 줄이고 유지보수성을 높일 수 있습니다.

3. 응답 코드는 성공과 실패를 함께 정의하기

API 문서에는 200, 201 같은 성공 응답뿐 아니라 400, 401, 403, 404, 500 같은 오류 응답도 함께 정의하는 것이 좋습니다.

오류 응답 구조까지 명확히 정의하면 클라이언트 개발자가 예외 상황을 더 안정적으로 처리할 수 있습니다.

4. 인증 방식은 명세에 포함하기

API가 인증을 필요로 한다면 components.securitySchemes와 security를 사용해 인증 방식을 명확히 정의해야 합니다.

예를 들어 Bearer Token 인증은 다음과 같이 정의할 수 있습니다.

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - bearerAuth: []

참고할 만한 도구

OpenAPI 문서를 작성하고 검증할 때는 다음 도구들을 활용할 수 있습니다.

Swagger Editor

OpenAPI 문서를 작성하고 실시간으로 검증해볼 수 있는 대표적인 도구입니다.

YAML 또는 JSON 형식으로 명세를 작성하면서 문법 오류나 구조 오류를 빠르게 확인할 수 있습니다.

Swagger UI

OpenAPI 문서를 기반으로 인터랙티브한 API 문서 페이지를 생성할 수 있습니다.

사용자는 문서 화면에서 API 구조를 확인하고, 설정에 따라 직접 요청을 테스트할 수도 있습니다.

Postman

OpenAPI 명세를 가져와 API 컬렉션, 테스트, 협업 워크플로에 활용할 수 있습니다.

API 설계, 테스트, 문서화 작업을 함께 관리할 때 유용합니다.

Stoplight

OpenAPI 기반 API 설계와 문서화를 지원하는 플랫폼입니다.

GUI 기반으로 API 명세를 작성하거나 검토할 수 있어 비개발자와의 협업에도 활용할 수 있습니다.

마무리

OpenAPI v3.0은 API를 단순히 설명하는 문서 형식을 넘어, API 설계와 개발, 테스트, 문서화, 협업을 연결하는 표준 명세입니다.

API를 OpenAPI 형식으로 정의해두면 개발자는 API 구조를 명확히 이해할 수 있고, 다양한 도구를 통해 문서 생성, 코드 생성, Mock Server 구성, 테스트 자동화까지 이어갈 수 있습니다.

RESTful API를 설계하거나 외부에 공개할 API를 운영한다면 OpenAPI 명세를 함께 관리하는 것이 장기적인 유지보수성과 협업 효율을 높이는 좋은 방법입니다.

참고로 Swagger Editor는 OpenAPI 3.x를 지원하는 편집 도구이고, Postman은 OpenAPI 3.0/3.1 정의를 YAML·JSON 형식으로 가져올 수 있습니다. Stoplight도 OpenAPI 설명서 작성, 문서화, Mock Server 기능을 제공하는 도구로 소개됩니다. (Swagger)

댓글 쓰기 · 수정

0 댓글