Swagger UI란
팀 내에서 업무에 필요한 서버를 띄우고 API를 서빙하고 있는데, API 스펙을 관리하고 시각화 하기 위해 Swagger UI를 도입하였다.
Swagger UI는 RESTful API를 문서화하고 시각화하는 오픈 소스 도구이다. Swagger UI를 사용하면 API 사용자가 API를 쉽게 이해하고 사용할 수 있도록 API의 엔드포인트, 매개변수, 요청 및 응답 본문 등을 시각적으로 표시할 수 있다.
Swagger UI의 주요 장점
-
문서화: Swagger UI를 사용하면 API 문서를 자동으로 생성할 수 있다. 이를 통해 API 사용자는 API를 쉽게 이해하고 사용할 수 있다.
-
시각화: Swagger UI는 API의 엔드포인트, 매개변수, 요청 및 응답 본문 등을 시각적으로 표시한다. 이를 통해 API 사용자는 API를 더 쉽게 이해하고 사용할 수 있다.
-
테스트: Swagger UI를 사용하면 API를 테스트할 수 있다. 이를 통해 API 사용자는 API를 더 쉽게 테스트하고 디버깅할 수 있다.
Swagger UI의 주요 단점
-
복잡성: Swagger UI는 복잡도가 높은 API의 경우 사용법을 잘 이해하고 있어야 한다. 또한 API의 변경 사항이 있을때마다 Swagger 스펙 문서를 업데이트해야한다. (물론, 이를 자동화할 수 있는 방법도 존재한다.)
-
보안: Swagger UI는 API의 엔드포인트, 매개변수, 요청 및 응답 본문 등을 모두 노출한다. 이를 통해 API 사용자가 API를 악용할 수 있는 가능성이 있다. 이를 해결하기 위해서는 API 보안을 강화하는 것이 중요하다.
Swagger 연동하기
Flask에서 Swagger를 연동할 때는 크게 두 가지 방식으로 나뉘는 것 같다. 첫 번째로는 flask의 blueprint를 사용해 모듈화하는 방법이고, 두 번째는 flask-restx의 namespace 객체를 사용하는 방법이다. 나는 blueprint를 사용하여 Swagger UI를 연동하였다.
참고차 기록해 두자면 blueprint로 등록된 Flask 애플리케이션은 Flask 애플리케이션의 일부분으로 동작한다. 따라서 blueprint로 등록된 Flask 애플리케이션은 Flask 애플리케이션의 URL 매핑을 공유하며, Flask 애플리케이션의 뷰 함수, 템플릿, 정적 파일 등을 사용할 수 있다.
또한 blueprint를 사용하면 Flask 애플리케이션을 여러 개의 모듈로 분리하여 개발할 수 있다. 예를 들어, Flask 애플리케이션의 라우팅, 뷰, 템플릿, 정적 파일 등을 각각의 blueprint로 분리하여 개발할 수 있다. 이를 통해 Flask 애플리케이션의 구조를 더욱 체계적으로 관리할 수 있다.
연동하는 코드 작성
Swagger UI 실행에 필요한 pip를 인스톨하고 flask의 blueprint에 register 해준다.
그리고 flask 서버를 시작하면 Swagger UI에 접근할 수 있다.
from flask import Flask, jsonify
from flask_swagger import swagger
from flask_swagger_ui import get_swaggerui_blueprint
app = Flask(__name__)
SWAGGER_URL = '/api/docs'
API_URL = '/api/spec'
YAML_PATH = read_config("ENV.SWAGGER_YAML_PATH") # yaml 파일 경로
swagger_ui_blueprint = get_swaggerui_blueprint(
SWAGGER_URL,
API_URL,
config={
'app_name': "My App",
"version": 1.0
}
)
app.register_blueprint(blueprint=swagger_ui_blueprint, url_prefix=SWAGGER_URL)
API 스펙 정의
API 스펙은 별도로 정의해야하는데 JSON 파일과 YAML 파일로 스펙을 정의할 수 있다. 작성 방법은 버전에 따라 조금 상이하기 때문에 공식 문서를 참고하는 것이 도움이 될 것 같다. 작성된 스펙에 대해서는 이 링크에서 테스트해볼 수 있다.
https://swagger.io/resources/open-api/
https://editor.swagger.io/
