프론트엔드와 백엔드 사이에서 정확히 어떠한 방식으로 데이터를 주고받을지에 대한 명세가 필요하기 때문에
API 명세( = 애플리케이션 간의 상호 작용을 정의하는 인터페이스)를 적절히 설계해야한다.
해피케이스의 경우가 아닌 에러를 반환할 수 있는 모든 경우에 대해 API를 설계해야 한다.
Swagger는 대표적인 API 관리 도구이다.
웹문서 자체에 API를 테스트할 수 있는 환경이 잘 마련되어있다.
API가 제대로 동작하는지 확인도 할 수 있다.
Swagger Hub는 다양한 프로젝트의 API 관리 기능을 지원해주는 스웨거 서비스이다.
여러 명의 개발자가 스웨거 허브에가입해 하나의 프로젝트에 대한 API를 작성 및 테스트해볼 수 있다.
OpenAPI는 RESTful API를 정의하고 명세하는 표준 형식이다.
API를 표준화하여 명확하게 문서화하고 개발자들이 API를 이해하고 시용할 수 있게 한다.
JSON 혹은 YAML 형식으로 작성된다.
OAI / OpenAPI - Specification
https://github.com/OAI/OpenAPI-Specification
GitHub - OAI/OpenAPI-Specification: The OpenAPI Specification Repository
The OpenAPI Specification Repository. Contribute to OAI/OpenAPI-Specification development by creating an account on GitHub.
github.com
SwaggerHub에 로그인하여 API 명세 작성 및 테스팅
SwaggerHub에 로그인 후,
Create New -> Create New API 클릭하여 API 명세를 작성할 수 있다.
Petstore 템플릿을 사용하면, 이미 제공되어있는 템플릿 기반으로 API 명세 작성 및 테스팅이 가능하다.
Template을 None으로 해서 API 명세를 직접 작성해보도록 하겠다.
위처럼 옵션 세팅을 맞추고 API 웹문서를 생성하였다.
👀 우선 첫째로, 서버로부터 get 요청을 받아오는 간단한 API 명세를 작성해보자.
JSONPlaceholder에서는 아래와 같이 테스팅을 위한 API 호출을 제공한다.
JSONPlaceholder - Free Fake REST API
{JSON} Placeholder Free fake and reliable API for testing and prototyping. Powered by JSON Server + LowDB. Serving ~3 billion requests each month.
jsonplaceholder.typicode.com
JSON placeholder API를 불러오는 yaml 파일을 작성 후, API 호출이 잘 되는지 테스팅하는 과정이다.
아래와 같이 yaml 파일을 작성한 후 save 버튼을 누르고, 바로 아래 사진의 문서 버튼을 클릭하면 작성된 API 명세를 웹문서로 조회 및 테스팅까지 해볼 수 있다.
✔️ yaml 파일에 API 호출할 server 주소, 엔드포인트 paths, 호출할 API의 CRUD, 호출 시 전달할 parameters, responses의 content 등을 원하는 API 형식대로 작성한다.
✔️ 작성한 API 명세를 웹문서로 조회한다.
✔️ 아래는 웹문서에 접속하여 작성한 API 명세가 잘 나오는지 테스트하는 화면이다.
response 200 OK가 제대로 오는 것을 확인할 수 있었다.
하나만 더 만들어보자.
이번엔 구글 검색 자동완성 API를 한번 호출해보자.
아까와 동일한 방식으로 ymal 파일을 작성한 후, API 명세대로 잘 동작하는지 확인한다.
API 테스팅
