OpenAPI (Swagger)

OpenAPI (Swagger)

RESTful API를 기술하기 위한 표준 명세 형식(YAML/JSON)으로, API의 엔드포인트, 파라미터, 요청/응답 구조, 인증 방식 등을 정의하며 문서 생성, 코드 생성, 테스트 도구와 연동되는 API 설계의 사실상 표준

목적: API 명세 표준화, 문서 자동 생성, 코드 생성, 테스트 지원, API 계약

특징: YAML/JSON 형식, 표준 명세, 도구 생태계, Design-First/Code-First, 다언어 지원

구성요소

• •info: API 제목, 버전, 설명, 연락처
• •servers: 서버 URL, 환경 (개발/스테이징/프로덕션)
• •paths: 엔드포인트, HTTP 메서드, 파라미터, 요청/응답
• •components: 재사용 스키마, 파라미터, 응답, 보안
• •security: 인증 방식 (OAuth, API Key, Bearer Token)

스키마 정의

• •parameters: path, query, header, cookie 파라미터
• •requestBody: 요청 본문 스키마
• •responses: 상태 코드별 응답 스키마
• •schemas: 데이터 모델 정의 (components/schemas)

도구 생태계

• •Swagger UI: 대화형 API 문서, 테스트 가능
• •Swagger Editor: OpenAPI 명세 작성/편집
• •Swagger Codegen / OpenAPI Generator: 서버/클라이언트 코드 자동 생성
• •Redoc: 깔끔한 API 문서 생성
• •Postman: OpenAPI 임포트, API 테스트

개발 방식

• •Design-First: 먼저 명세 작성 → 코드 생성, 계약 명확, 병렬 개발 가능
• •Code-First: 먼저 코드 작성 → 명세 자동 생성, 빠른 시작, 명세 불일치 위험

장점: 표준화, 문서 자동화, 코드 생성, 테스트 지원, 협업 향상

단점: 학습 곡선, 명세 유지 부담, 복잡한 API 표현 한계

적용사례: 공개 API, 마이크로서비스, API Gateway, 팀 간 협업

기술요소: YAML, JSON Schema, Swagger UI, OpenAPI Generator, Redoc

비교: OpenAPI(REST) vs AsyncAPI(이벤트/메시징) vs GraphQL Schema(GraphQL) vs gRPC Proto(gRPC)

연관: REST API, API Versioning, Swagger, API Gateway, Design-First