OpenAPI Specification(OAS)은 RESTful API를 표준화된 형식으로 기술하기 위한 개방형 표준입니다. 본 보고서는 효과적인 OAS 작성을 위해 반드시 포함해야 할 핵심 요소와 선택적 구성요소를 체계적으로 분석합니다.
OpenAPI Specification의 기본 구조
OAS 문서는 JSON 또는 YAML 형식으로 작성되며, 최소한 다음 필수 요소를 포함해야 합니다:
openapi: 3.1.0
info:
title: API 제목
version: 1.0.0
paths: {}
1. OpenAPI 버전 선언
openapi필드는 사용 중인 OAS 버전을 명시(예: 3.1.0)- 툴링 시스템이 명세서를 올바르게 해석할 수 있도록 반드시 최상위에 위치
2. 정보 객체(Info Object)
info섹션은 API의 메타데이터를 포함:- title: API의 공식 명칭(필수)
- version: API 버전(필수)
- description: API 기능 상세 설명
- termsOfService: 서비스 약관 URL
- contact: 개발팀 연락처 정보
- license: 적용 라이선스 정보
예시:
info:
title: 주문 관리 시스템
description: 전자상거래 플랫폼의 주문 처리 API
version: 2.3.1
contact:
name: 기술 지원팀
url: https://support.example.com
email: support@example.com
핵심 구성 요소
3. 경로 정의(Paths Object)
- API 엔드포인트와 HTTP 메서드 매핑:
/users와 같은 상대 경로로 표현- 각 경로별로 get/post/put/delete 작업 정의
- 매개변수, 요청 본문, 응답 형식 상세 기술
예시:
paths:
/users:
get:
summary: 사용자 목록 조회
parameters:
- name: limit
in: query
schema:
type: integer
4. 구성 요소(Components Object)
- 재사용 가능한 요소들을 그룹화:
- schemas: 데이터 모델 정의
- parameters: 공통 매개변수
- securitySchemes: 인증 방식
- responses: 표준 응답 형식
예시:
components:
schemas:
User:
type: object
properties:
id:
type: integer
name:
type: string
5. 서버 구성(Servers Object)
- API 기본 URL 및 환경별 설정:
- 개발/테스트/운영 환경별 서버 목록 정의
- 변수 템플릿을 활용한 동적 URL 구성 가능
예시:
servers:
- url: https://{environment}.example.com/v1
variables:
environment:
default: api
enum:
- dev
- test
- prod
고급 구성 요소
6. 보안 체계(Security Schemes)
- API 접근 제어 메커니즘 정의:
- API 키: 헤더/쿼리 파라미터 기반
- OAuth 2.0: 권한 부여 흐름 설정
- OpenID Connect: 인증 프로토콜 통합
예시:
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
7. 태그 관리(Tags Object)
- 관련 작업 그룹화를 위한 분류 시스템:
- Swagger UI에서 작업 그룹 표시
- 설명 필드를 통한 추가 문서 제공
예시:
tags:
- name: 인증
description: 사용자 인증 관련 엔드포인트
- name: 주문
description: 주문 처리 관리 기능
8. 외부 문서 연결(External Docs)
- 추가 설명이 필요한 경우 외부 문서 링크:
- 전체 API 문서 또는 특정 작업 관련 가이드
- 기술 문의 채널 또는 커뮤니티 포럼 연결
예시:
externalDocs:
description: 전체 API 문서
url: https://docs.example.com
검증 및 테스트 고려사항
9. 예시 데이터(Examples)
- 요청/응답 샘플 데이터 제공:
- 개발자 이해도 향상
- 자동화 테스트 케이스 생성 기반
10. 유효성 검사 규칙
- 데이터 무결성 보장을 위한 제약 조건:
- 문자열 패턴 정규식
- 숫자 범위 제한
- 열거형 값 설정
예시:
parameters:
- name: status
in: query
schema:
type: string
enum:
- pending
- completed
- cancelled
OAS 작성 모범 사례
문서화 품질 관리
- 모든 엔드포인트에 명확한 요약(summary)과 설명(description)
- 오류 코드별 응답 형식 상세 정의
- API 버전 관리 전략 수립
툴링 연계
- Swagger UI/Editor를 활용한 문서 자동 생성
- Postman 컬렉션 생성 자동화
- 코드 제너레이션 도구 연동
버전 관리
- semver(유의적 버전) 규칙 적용
- 주요 변경사항에 대한 마이그레이션 가이드 제공
- Deprecation 정책 명시
0 댓글