API 설계 우선 방식과 OpenAPI Specification

https://www.youtube.com/watch?v=28Tz7gos5DQ 

 

NHN Cloud 메시징플랫폼개발팀의 신진호 님의 영상을 요약한 내용입니다.

 

 

API 우선 방식(API First)

우선 전략과 전술에 대해 먼저 설명합니다.

전략 : 어떤 목표를 위해 어떻게 나아갈지에 대한 큰 틀

전술: 어떠한 목적을 달성하기 위한 수단이나 방법

 

API First를 전략에 비유하고, Code First를 전술에 비유합니다.

 

API First 방식이라고도 하며 first는 서비스 기획, 개발 시 가장 중요하게 고려함을 뜻합니다.

이와 대비대는 방법으로 Code first로 기능개발을 먼저로 두고 API는 제공하기 위한 수단으로 활용합니다.

 

 

API 설계 우선 방식 (API Design First)

API First가 접근법이라면 API Design First는 방법론입니다.

즉, API First를 어떻게 해야할지에 대한 방법을 제시하며 이에 대해 구체적인 구현은 OpenAPI Specification을 통해 이루어집니다.

 

API 설계 문서를 Contract라고 부릅니다.

API 설계 즉,계약이 되지 않으면 다음 단계로 넘어가지 않습니다.

 

사용하면서 느낀 장점

• 업무 효율 상승
• 개발자 경험 개선
• 상호 운영 능력 개선
• 실패 위험 감소
• 의사 소통 개선

 

 

OpenAPI Specification의 역사

HTTP API 설계 방법에 대한 표준화를 목표로 두고 있으며 Linux Foundation 산하의 오픈소스 프로젝트입니다.

25.3k의 Github starts를 받고 있습니다.

 

2011년에 Swagger라는 이름으로 공개가 되었습니다.

2014년에 2.0 출시

2015년에 OpenAPI Initiative라는 이름으로 Linux Foundation에 기증되었습니다.

그 후 3.0 3.1이 출시되었습니다.

 

 

OpenApi Specification과 Swagger의 차이점

OpenApi Specification은 스펙 그 자체이며 Swagger는 그에 대한 구현체입니다.

 

OpenAPI Specification

특정 언어에 독립적으로 API Contract 파일을 이용하여 Server/Client 코드를 생성할 수 있습니다.

OpenAPI Specification의 구조

 

 

겪었던 시행착오1 - 용어 통일

기존의 푸시, 문자, 이메일, 카카오톡등의 파편화된 서비스들을 facade 하여 Notification 서버가 제공합니다.

이때 푸시, 문자. 이메일, 카카오톡에서 용어들이 비슷하지만 달랐습니다.

예를들어 수신자를 to, recevier, recipient 등으로 용어를 다양하게 사용하고 있었습니다.

이를 해결하기 위해 하나의 용어로 통일하는 작업을 꾸준하게 진행하고 있습니다.

 

겪었던 시행착오 2 - API 설계 문서 관리

설계하는 API가 많아지면 자연스럽게 문서도 커지게 됩니다.

json reference를 통해 파일을 분리하고 참조하여 중복을 제거할 수 있습니다.

 

하지만 다양한 버전과 종류들의 API가 존재했고 더 분할해서 관리할 필요성이 생겼습니다.

path item 객체 아래에 파일참조가 가능하여 해결

 

이후 path 객체에서 파일참조가 가능한지 찾아보았고 관련하여 이슈에서 이야기 중입니다.

 

겪었던 시행착오 3 - 확장

확장은 꼭 필요한 부분이지만 OpenAPI Specification에 대한 지식이 없으면 이해하기 어려울 수 있습니다.

프로그래밍 언어에 독립적이기 때문에 특정 언어에만 맞는 기능을 지원하기 어렵습니다.

 

예를 들어 java의 bean validation을 지원하지 않습니다.

OpenAPI Specification에는 확장을 위해 x-imports, x-valids 등을 지원합니다.

 

Bean Validation이란

@NotBlank @EnumValue(enumClass = SedingType.class)
private string sendingType;

//각 필드에 정의된 애너테이션으로 필드의 값을 검증

 

작성된 Contract는 OpenAPI Generator를 통해 Spring Code가 생성됩니다.

이를 위해서는 OpenAPI Generator를 확장 구현해야 하며 Mustache라는 템플릿언어를 수정하여 확장을 할 수 있었습니다.

 

이를 코드로 보면 다음과 같습니다.

확장을 위해서는 OpenAPI Specifitaion, OpenAPI Generator, Mustache에 대한 이해가 필요합니다.

 

 

 

겪었던 시행착오 4 - 사소한 오류

설계 후 소스코드 생성 시 Mock API를 호출해 볼 수 있는 것이 장점입니다.

Spring Webflux 기반으로 코드를 생성하였으나 Bean Validation이 생성되지 않았습니다.

Mono Flux에서 Bean Validation이 동작하기 위해서는 로직상에서 호출이 되어야 합니다.

이런 문제점을 PR로 올려 OpenAPI Generator 6.2.1에 반영되었습니다.

 

 

정리

• API Contract
• 완벽하기 않지만 발전하는 중
• 구조에 대한 이해 필요, 학습 비용이 있음
• 하지만, 중요한 건 꺾이지 않는 마음