Swagger

Swagger란?

개발자 또는 엔드 유저가 별도의 구현 로직 없이 API 리소스를 시각화하고 상호 작용할 수 있도록 도움을 준다. 또한, Swagger는 Open API로 해당 사양에 맞게 시각적 문서를 자동 생성해준다. 문서는 백엔드 구현 및 클라이언트 측 사용을 쉽게 할 수 있게 한다.

Open Api Specification(OAS)를 위한 프레임워크이다.

Swagger-editor를 통해 api를 문서화하고 빠르게 명세 가능하며, Swagger-UI를 통해 작성된 API를 시각화시켜준다.

swagger open api 활용

1. Docker 활용

도커 이미지를 가져와 활용하는 방법으로 editor와 ui 모두 swagger 공식 github에 방법이 기재되어있다. 요약하면 아래와 같다.

#도커는 지난 포스트에 있는 방법으로 설치된 상태

swagger-editor

#이미지 pull을 통해 editor를 다운로드한다.
docker pull swaggerapi/swagger-editor
#도커 내부에 있는 nginx서버로 실행 할 수 있다.
docker run -d -p 80:8080 swaggerapi/swagger-editor

위의 명령어를 진행 후 Swagger-Editor를 80포트로 브라우저에서 실행 가능하다. (http://localhost)

작성한 spec (json 또는 yaml) 형식을 도커 볼륨 마운트를 통해 open하여 수정할 수 있다.

docker run -d -p 80:8080 -v $(pwd):/tmp -e SWAGGER_FILE=/tmp/swagger.json swaggerapi/swagger-editor

swagger-ui

docker pull swaggerapi/swagger-ui
docker run -p 80:8080 swaggerapi/swagger-ui

8080포트로 브라우저에서 실행가능하다.

또한, 작성한 spec을 볼룸 마운트 하는 방법은 아래와 같다.

docker run -p 80:8080 -e SWAGGER_JSON=/foo/swagger.json -v /${doc-path}:/foo swaggerapi/swagger-ui

2. npm 활용

swagger editor, ui를 github에서 다운로드 진행을 한다.

swagger-editor

npm start

npm을 실행시켜 index.html을 열면 브라우저에서 스펙을 편집 할 수 있다.

swagger-ui

ui의 소스는 /dist폴더에 작성되어있으며, 해당폴더에 swagger.json(스펙문서)를 저장시켜 브라우저에서 출력 할 수 있다.

다만, 서버를 npm에서 실행 시켜줘야 한다. 우선 서버를 npm에서 설치한다.

npm install -g http-server

/dist폴더의 index.html에서 spec을 추가히기 위해 spec.js를 생성하고 editor에서 작성한 json을 var spec = 이후 값으로 작성하고 파일을 생성한다.

index.html에 spec.js파일을 추가해준다.

<script src='spec.js' type="text/javascript"></script>

그리고 파라미터를 spec에 넣어준다.

window.swaggerUi = new SwaggerUi({
    url: url,
    spec: spec,
    dom_id: "swagger-ui-container",

그리고 http-server를 실행하여 index.html를 브라우저에서 확인한다.

npm http-server ./dist -p {포트}

swagger-ui 서버 구축

윈도우 운영환경에서 서버를 구축을 해야하는 상황으로 npm을 활용하여 구축하였다. http-server를 백그라운드에서 실행하기위해 pm2를 활용하여 구축 하였으며, 방식은 아래 url을 참고하여 진행하였다.

1. http-server의 위치를 찾는다. (ex C:\Users{유저명}\AppData\Roaming\npm\node_modules\http-server\bin\http-server)
2. 해당 디렉토리로 이동
3. pm2 실행 npm pm2 start C:\Users\{유저명}\AppData\Roaming\npm\node_modules\http-server\bin\http-server ./dist -p {포트}