OpenAPI v3.0란?


 

OpenAPI v3.0(OAS 3.0)은 RESTful API를 정의하고 문서화하기 위한 표준 명세입니다. 원래 Swagger로 불렸던 명세가 2016년 OpenAPI Initiative에 의해 관리되면서 오픈API로 명명되었습니다. OAS 3.0은 API의 구조, 리소스, 동작, 입력/출력 데이터 형식, 인증 방법 등을 YAML 또는 JSON 형식으로 표준화해 기술할 수 있게 해줍니다. 이 표준을 사용하면 다음과 같은 이점이 있습니다:

  • 명확한 API 문서화: 개발자와 사용자 모두 API를 빠르게 이해 가능
  • 자동화 도구 활용: code generator, API 문서 생성, Mock Server 등 다양한 도구와 연동
  • 일관성 유지: 다양한 팀에서 개발 해도 동일한 기준 유지 가능

OpenAPI v3.0의 주요 구성 요소

  1. openapi: 명세의 버전 (예: "openapi": "3.0.0")
  2. info: API 정보 (title, description, version 등)
  3. servers: API 서버 목록 (URL 및 설명)
  4. paths: 엔드포인트와 각 경로의 동작 (HTTP 메서드별)
  5. components: 재사용 가능한 스키마, 매개변수, 응답, 보안 스키마 등
  6. security: API 보안 방식 정의
  7. tags: API 그룹화 및 분류
  8. externalDocs: 추가 문서 링크

OpenAPI v3.0 예제들

예제 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

예제 2: 파라미터와 응답 객체 사용

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
      properties:
        id:
          type: integer
        name:
          type: string

예제 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'
components:
  schemas:
    Post:
      type: object
      properties:
        title:
          type: string
        content:
          type: string
        author:
          type: string


참고 자료 및 도구






댓글

댓글 쓰기