OpenAPI 기본 구조

OpenAPI 기본 구조 (Basic Structure)

REST API를 다른 팀이나 도구가 이해하려면 "어떤 엔드포인트가 있고, 어떤 데이터가 오가는지"를 기계가 읽을 수 있는 형태로 남겨야 해요. OpenAPI는 그걸 YAML 또는 JSON으로 정의하는 표준이에요.

출처: https://swagger.io/docs/specification/basic-structure/

OpenAPI 정의는 YAML이나 JSON으로 쓸 수 있어요. 아래는 OpenAPI 3.0 정의의 골격이에요.

openapi: 3.0.4
info:
  title: Sample API
  version: 0.1.9
servers:
  - url: http://api.example.com/v1
paths:
  /users:
    get:
      summary: Returns a list of users.
      responses:
        "200":
          description: A JSON array of user names
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

구조를 항목별로 살펴볼게요.

  • openapi: 이 정의가 기반으로 하는 OpenAPI 버전이에요. 버전이 구조(무엇을 어떻게 문서화하는지)를 결정하죠. 3.0.0부터 3.0.4까지는 기능적으로 동일해요.
  • info: API의 메타정보예요. title, 설명 description(CommonMark 마크다운 지원), version이 들어가요. version은 API 자체 버전이지 파일 리비전이나 openapi 버전과는 달라요. arbitrary string이라 1.0-beta처럼 써도 돼요.
  • servers: API 서버와 기본 URL이에요. 프로덕션·샌드박스처럼 여러 개 정의할 수 있고, 모든 경로는 이 서버 URL 기준이에요. /users는 http://api.example.com/v1/users가 되는 식이죠.
  • paths: 각 엔드포인트와 그 위의 HTTP 메서드(operation)를 정의해요.

모든 키워드 이름은 대소문자를 구분해요. 이 기본 구조만 봐도 "어느 버전 스펙, 어떤 서버, 어떤 경로·메서드가 있는지"가 한눈에 드러난다는 게 OpenAPI의 장점이에요.

더 알아보기