OAS(OpenAPI Specification)

OAS(OpenAPI Specification)

• OpenAPI Specification (OAS)는 RESTful API를 기술하고 문서화하기 위한 업계 표준입니다.
• OpenAPI는 API의 명세(specification)를 JSON 또는 YAML 형식으로 작성할 수 있도록 하며, 이를 통해 API의 구조를 명확히 정의하고 자동화된 도구와 연계할 수 있습니다.

OAS의 주요 특징

• RESTful API의 표준화
  • API의 요청(Request)과 응답(Response) 구조를 명확하게 정의할 수 있음.
• JSON 또는 YAML 기반
  • 사람이 읽기 쉽고 기계가 처리하기 쉬운 형식(JSON/YAML)으로 API를 기술함.
• 자동 문서화 지원
  • Swagger UI, Redoc, Stoplight Studio 등 다양한 도구와 연계하여 API 문서를 자동 생성할 수 있음.
• API 검증 및 테스트 지원
  • OpenAPI 명세를 기반으로 API를 자동으로 검증하거나 테스트할 수 있음.
• 코드 생성 및 API 게이트웨이 연계
  • OpenAPI 명세를 활용하여 클라이언트 및 서버 코드, SDK, 스텁 코드 등을 자동으로 생성할 수 있음.
  • AWS API Gateway, Apigee 등의 API 관리 플랫폼과 연동 가능

2. OAS 버전별 주요 변화

(1) OpenAPI 2.0 (Swagger 2.0)

• 2014년에 Swagger 프로젝트에서 OpenAPI로 발전함.
• JSON 및 YAML 형식 지원.
• swagger: "2.0"을 사용하여 명세 시작.
• API의 paths, definitions(Schema 정의), parameters, responses 등의 구조 사용.

(2) OpenAPI 3.0

• 2017년 발표된 주요 업데이트 버전.
• swagger: "2.0" 대신 openapi: "3.0.0" 사용.
• components 섹션 도입 (기존 definitions, parameters, responses 통합).
• requestBody 추가 (이전 버전에서는 parameters에 포함).
• links 개념 도입 (API 간 연관 관계 명시).

(3) OpenAPI 3.1

• 2021년 발표된 최신 버전.
• JSON Schema 2020-12 완전 지원.
• nullable 속성 제거 (대신 JSON Schema의 type: ["string", "null"] 방식 사용).
• webhooks 지원.

OpenAPI Specification 예제

다음은 OpenAPI 3.0을 사용하여 간단한 GET /users API를 정의한 YAML 예제입니다.

openapi: 3.0.0
info:
  title: 사용자 관리 API
  description: 사용자 정보를 관리하는 API입니다.
  version: 1.0.0

servers:
  - url: https://api.example.com/v1
    description: 프로덕션 서버

paths:
  /users:
    get:
      summary: 모든 사용자 조회
      description: 시스템에 등록된 모든 사용자의 목록을 반환합니다.
      responses:
        "200":
          description: 성공적으로 사용자 목록을 반환
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string
                    email:
                      type: string

OpenAPI Specification 관련 도구

OpenAPI는 다양한 도구와 함께 활용될 수 있습니다.

도구	설명
Swagger UI	OpenAPI 문서를 웹 인터페이스로 시각화
Swagger Editor	웹 기반 OpenAPI 작성 및 검증 도구
Redoc	미려한 API 문서 생성기
Postman	OpenAPI 파일을 가져와 API 요청 테스트 가능
Stoplight Studio	GUI 기반 OpenAPI 편집 도구

 

OpenAPI 활용 사례

• API 문서 자동화: API 문서를 따로 작성하지 않고, OpenAPI 명세에서 직접 생성.
• API Mocking: OpenAPI 명세 기반으로 가짜(Mock) 서버를 만들어 개발 초기 테스트 가능.
• 코드 자동 생성: OpenAPI 명세에서 클라이언트 및 서버 스텁 코드 생성 (e.g., openapi-generator).
• API 테스트 자동화: OpenAPI를 기반으로 API 테스트 자동화 가능.

OpenAPI와 기타 API 표준 비교

표준	설명
OpenAPI (OAS)	RESTful API 문서화를 위한 표준
GraphQL	클라이언트가 원하는 데이터만 요청할 수 있는 API 쿼리 언어
gRPC	프로토콜 버퍼 기반의 빠르고 효율적인 RPC 프레임워크
RAML	RESTful API Modeling Language, OpenAPI와 유사한 API 정의 언어