OAS(OpenAPI Specification) - YAML 파일로 Swagger API 명세 만들기
소프트웨어 마에스트로 14기 팀 프로젝트에서 나는 백엔드 파트를 담당하여 Spring Boot를 통한 API 서버 개발을 하게 되었다. 이를 위해 학습 차 게시글을 작성하게 되었다.
API 명세 포맷
API 명세 포맷을 사용하는 이유
Microsoft Office Excel이나 Notion 등으로도 프로그래밍 인터페이스를 설명할 수 있고, 다른 사람들과 공유도 가능하다. 하지만 버전 관리, 문서 자동 생성, 문서 코드 생성, 문서 바탕 API 연관 도구 설정 등이 어렵다는 문제가 있고, API 명세 포맷을 사용함으로써 디자인 단계를 포함해 API LifeCycle 전반적으로 이점을 가질 수 있다고 한다.
API 명세 포맷 장점
1. 코드를 작성하듯이 API를 효율적으로 사용할 수 있다.
OAS 문서는 단순 텍스트 파일 형태로 Git과 같은 VCS에 쉽게 저장이 가능하다. 이를 통해 API 디자인을 반복하는 동안 간단하게 버전을 지정하고, 수정사항을 추적할 수 있다. 또한 Resource, Action, Parameter, Response 등에 대해 작성하고, 재사용 가능한 컴포넌트(데이터 모델) 정의를 통해 프로그래밍 인터페이스를 보다 효율적으로 설명할 수 있게 해주고, 귀찮은 API 명세의 Copy & Paste 반복을 피할 수 있도록 도와준다. OAS 문서를 작성할 때는 텍스트 에디터를 사용하는 것도 좋지만, editor.swagger.io와 같은 온라인 에디터도 있으니 참고하면 좋을 것 같다.
2. API 명세 및 문서를 손쉽게 공유할 수 있다.
OAS 문서는 타인에게 API 디자인에 대해 공유하고 피드백 받기 쉬운 수단이다. 내부 시스템에서 사용되는 특정 포맷은 소수만 이해할 수 있지만, OAS 포맷으로 작성된 문서는 널리 통용되어 많은 사람들이 한번에 이해할 수 ㅣㅇ싿. 또한 OAS 문서 양식에 익숙하지 않은 사람들을 위해, Swagger UI와 같은 도구를 통해 OAS 문서 사용을 위해 사용 가능한 모든 Resource와 Action을 보여주는 API 참조 문서를 생성할 수도 있다.
3. 목업을 생성할 수 있다.
API 명세 포맷으로 API를 디자인했다면, 이 명세 포맷을 바탕으로 일부 구현 코드를 만들거나, 소스 코드 내용이 없는 뼈대를 구성하거나, 동작하는 목업을 생성할 수 있다. 텍스트 파일 형태의 OAS 명세 포맷을 통해 API 소비 코드를 바로 생성하는 API 명세 장점을 취할 수 있다. 또한 API 명세 포맷 사용으로 API나 보안 도구 테스트를 수행할 수도 있으며, 이미 개발된 다양한 API 관계 도구들도 사용할 수 있다. 예로 API Gateway Solution은 OAS 같은 API 명세 파일로 API 제공 프록시에 설정할 수 있다.
YAML 파일
정의
YAML은 XML, C, 파이썬, 펄, RFC2822에서 정의된 e-mail 양식에서 개념을 얻어 만들어진 ‘사람이 쉽게 읽을 수 있는’ Key - Value 형태의 데이터 포맷의 데이터 직렬화 양식이다. YAML이라는 이름은 “YAML은 마크업 언어가 아니다 (YAML Ain’t Markup Language)” 라는 재귀적인 이름에서 유래되었고, 오늘날 XML과 JSON이 데이터 직렬화에 주로 쓰이기 시작하면서, 많은 사람들이 YAML을 ‘가벼운 마크업 언어’로 사용하려 하고 있다고 한다.
YAML 작성 시 유의사항
"는 속성과 값에서 허용되지 않음- JSON의 경우에는
{}와,를 구분자로 사용하지만, YAML은 줄바꿈과 들여쓰기로 구분함 - JSON 배열에서 쓰는
[],,는 YAML에서는-와 줄바꿈으로 대체함 - 문자 시작에서
#을 사용하여 주석 처리가 가능함
