OpenAPI
REST API는 인터넷 환경에서 가장 보편적이고 효과적인 커뮤니케이션 방법이다. 게다가 SSL과 JWT등과 같은 보안을 강화해주는 다양한 방법도 있다. 그래서 대부분의 어플리케이션은 API 기반으로 설계되고 운영되고 있다. OpenAPI는 이런 커뮤니케이션을 표준화할 수 있도록 하며, 이런 표준화된 API 스펙을 사용함으로 쉽고 빠르게 서비스를 개발하는게 가능해진다.
What is OpenAPI?#
The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.
An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases.
OpenAPI with Kupboard#
kupboard는 openapi 포맷에 맞게 작성된 spec이 있다면 별도의 개발과정 없이 서버 컨테이너를 빌드하고 배포까지 가능하다. 심지어 임의의 데이터를 생성해서 리턴해주는 테스트서버도 배포가 가능하다.
Demo#
kupboard-data-sample.tar.gz 예제를 사용하여 kupboard의 OpenAPI 기능을 살펴본다.
예제에 포함된 data/api/demo.yaml은 OpenAPI Spec 3.0 기반으로 작성된 스펙이며 API /v1/demo/list가 정의되어 있다.
Build#
data/api 디렉토리에 위치한 OpenAPI 스펙을 사용하여 어플리케이션을 배포하기 위해서는 build 명령어를 사용한다. 그리고 임의의 데이터를 제공해주는 mockup 어플리케이션을 배포하기 위해서는 --mock 옵션을 사용한다. 이렇게 빌드된 어플리케이션의 컨테이너 이미지는 자동으로 Harbor 레지스트리에 push되어 배포할 때 사용된다.
위와 같은 방법으로 배포된 어플리케이션을 외부에서 접근하기 위해서는 gateway도 함께 배포해야 한다. 우선 gateway를 빌드하기 위해서는 -s gateway와 같이 서비스 이름을 gateway로 지정하면 된다.
note
build 명령어로 빌드 및 배포되는 gateway는 쿠버네티스에 배포되는 어플리케이션이며 gateway 클러스터와는 다르다.
Deploy#
OpenAPI 어플리케이션과 gateway의 빌드가 완료되었으면 deploy 명령어를 사용하여 배포할 수 있다. 빌드와 마찬가지로 mockup 어플리케이션을 배포하기 위해서는 --mock 옵션을 사용해야 한다.
note
OpenAPI 어플리케이션과 gateway가 배포된 후 외부에서 접근하기 위해서는 Nginx 패키지를 gateway 클러스터에 설치해야 한다. Nginx가 설치되면 app.mycompany.com 또는 mock.mycompany.com으로 배포된 어플리케이션에 접근이 가능하다.