메뉴

문서정보

목차

언제나 그렇듯이 우분투 리눅스 기준이다.

Swagger에 대해서

Swagger는 API 개발을 위한 툴셋이다. 개발자는 툴셋을 이용해서 코드 명세를 관리 할 수 있으며, 웹으로 배포해서 다른 개발자들 QA, 운영자와 소통 할 수 있다. 이 것은 매우 중요하다.

RESTAPI 기반 서비스를 만든다고 가정해보자. 서버 개발자가 swagger로 스펙을 잘 정의하면, 클라이언트 개발자는 해당 문서를 보고 개발하면 된다. QA는 해당 문서를 보고 테스트 시나리오와 테스트 케이스를 만들어서 품질관리 활동을 할 수 있다.

Swagger는 아래와 같이 CICD와 통합 할 수 있다.

Swagger CLI 툴 설치

Swager CLI 는 yaml로 만든 swagger api 파일이 올바른지를 검사하고 swagger-ui가 읽어서 출력 할 수 있는 json로 변경하는 등의 일을 한다. 또한 swagger 파일로 부터 서버/클라이언트 코드를 만드는 일을 한다.

Swagger로 부터 서버/클라이언트 코드를 만드는 것은 언뜻 굉장히 멋져보인다. 개발자가 작성한 스펙문서로 부터 코드가 생성되므로, 문서와 코드가 완벽하게 일치할 것이기 때문이다. 매우 멋질 것 같아서 swagger 스펙문서로 부터 코드를 만들어본 적도 있는데, 그냥 사용하지 않기로 했다. 지금은 스냥 스펙문서를 코드와 분리해서 개발하고 있다.

# apt-get install gnupg ca-certificates
# apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 379CE192D401AB61
# echo "deb https://dl.bintray.com/go-swagger/goswagger-debian ubuntu main" | tee /etc/apt/sources.list.d/goswagger.list
# apt-get update
# apt-get install swagger
# swagger version
version: v0.22.0
commit: 5773cbe63c3f459b23ed73ad8b482389ddf46cb4

Swagger UI 설치

Docker로 설치한다.
# docker pull swaggerapi/swagger-ui

Swagger Docker 컨테이너를 실행한다. 아직 swagger.json 파일이 없을테니, 감만 익히도록 한다.
# docker run -p 80:8080 -e SWAGGER_JSON=/foo/swagger.json \
	-v /home/yundream/swagger:/foo swaggerapi/swagger-ui
컨테이너를 실행하면 /foo/swagger.json 파일을 읽어서 출력한다. 대략 아래와 같은 모습이 될 것이다.

swagger API문서 작성

CICD와 결합하기