OpenAPI 와 Swagger/redoc 란

OpenAPI Spec

OpenAPI Specification (OAS) 은 RESTful API 를 기술하는 표준으로 서비스에서 제공하는 API 의 기능과 End Point 를 개발자나 시스템이 자동으로 발견하고 처리하는데 필요한 정보를 제공합니다.

OAS 는 json 이나 yml 형식으로 기술해야 하며 OAS 파일을 읽어서 디플로이 해주는 도구(Ex: swagger-ui)를 사용하면 아래와 같이 브라우저에서 편리하게 API 문서를 볼 수 있습니다.

OAS 는 예전에는 Swagger spec 으로 불렸으며 3.0 부터 OpenAPI 3.0 Specification 라는 이름으로 표준화되었습니다.

Swagger 는 OpenAPI Spec 에 맞게 디자인하고 문서화하고 빌드하기 위한 도구들의 모음으로 다음과 같은 구성 요소로 이루어져 있습니다.

Swagger Editor – 브라우저 기반의 편집기로 OpenAPI spec 을 쉽게 작성할 수 있도록 도와줍니다.
Swagger UI – OpenAPI spec 문서를 디플로이하고 브라우저에서 예쁘게 표시할 수 있도록 해줍니다. swagger-ui 대신 아래에서 설명할 redoc 을 사용해도 됩니다.
Swagger Codegen – OpenAPI spec 에 맞게 Server 나 Client 의 stub code 를 생성해 줍니다. 개발자는 생성된 코드에 비즈니스 로직에 집중해서 구현하면 됩니다.

OpenAPI spec 을 웹에서 제공하려면 swagger-ui 를 설치하고 제공하려면 의존성이 많아서 도커로 설치해서 관리하는 게 편리합니다.

docker pull swaggerapi/swagger-ui

SWAGGER_JSON 변수에 작성한 OpenAPI spec 파일의 이름을 지정하고 이 파일이 있는 볼륨을 마운트해줍니다.

예로 /var/www/swagger-proj/my-openapi.yml 이 Host 에 있을 경우 이를 volume 으로 매핑해 주면 됩니다.

docker run -p 8080:8080 -e SWAGGER_JSON=/mnt/my-openapi.yml -v /var/www/swagger-proj/:/mnt swaggerapi/swagger-ui

redoc 은 OpenAPI Spec 파일을 읽어서 디플로이해주는 도구로 Swagger-UI 와 비슷한 역할을 수행합니다.

설치와 사용이 아주 간편한 장점이 있지만 swagger-ui 랑 달리 브라우저에서 API TEST 기능을 해볼수는 없는 단점이 있습니다.

redoc은 local에서 작성한 API 가 제대로 문서화되었는지 빠르게 확인할 때 테스트할 때 유용합니다.

redoc 설치는 다음 명령을 실행하면 됩니다.

npm -i g redoc-cli

OpenAPI Spec 을 myopenapi.yml 이라는 이름으로 했을 때 다음 명령으로 하나의 파일로 번들링할 수 있습니다.

redoc-cli bundle -o public/myopenapi.html myopenapi.yml

이제 웹 서버를 통해서 번들링한 myopenapi.html 을 서비스하면 됩니다.

로컬에서 사용중이라면 번들링해서 웹 서버로 서빙하지 말고 redoc-cli 를 사용하면 됩니다.

redoc-cli serve  myopenapi.yml