Swagger UI를 다루면서 몇 가지 해결하지 못했던 문제 또는 예상하지 못했던 문제를 직면했던 기록을 남겨두자.
(간단히 라우팅하여 운영할 수 있을 것으로 생각했는데, 역시나 직접 구현하다보면 예상치 못한 문제를 많이 직면하게 되는듯하다 ㅎㅎ)
Swagger UI는 기본적으로 알파벳 순으로 정렬된다.
아래와 같이 API Spec이 정의되어 있다고 가정해 보자.
properties에 timestamp가 먼저 정의되어 있으나 Swagger UI 상에서는 market이 먼저 노출된다. 이를 해결하기 위해 x-ordering, orderDisplay 등의 방법이 있다고는 하나, 테스트해 보니 동작하지 않는듯하다. openapi의 버전이나 라이브러리에 따라 지원 여부가 상이한듯하다.
오랜 시간을 들여 해결해야 하는 문제는 아니라서 가볍게 넘어갔으나, 추후 해결 방법을 강구해서 업데이트할 예정이다.
responses:
200:
description: 성공
schema:
type: array
items:
type: object
properties:
timestamp:
description: 호가 생성 시각
type: integer
example: 1704871103076
market:
description: 마켓 코드
type: string
example: KRW-BTC
net::ERR_CONTENT_DECODING_FAILED 에러가 발생할 수 있다.
Swagger UI를 통해 요청된 API의 응답을 gzip으로 리소스를 압축하여 응답을 주었는데, Swagger UI에서 이를 받아주지 못하여 net::ERR_CONTENT_DECODING_FAILED 에러가 발생하였다.
net::ERR_CONTENT_DECODING_FAILED 오류는 일반적으로 서버에서 전송된 응답이 잘못 압축되었거나, 브라우저에서 지원하지 않는 압축 형식으로 압축되었을 때 발생한다. 일반적으로 이 오류를 해결하기 위해서는 서버에서 전송된 응답이 올바르게 압축되었는지 확인해야 하는데, 나는 다른 서버의 API 응답을 bypass 하여 라우팅하고 있었기에 이를 직접 해결하기보다는 Swagger UI 요청 응답에 대한 헤더에 headers["Content-Encoding"] = "identity" 를 추가하여 압축하지 않고 응답을 주도록 우회하여 문제를 해결하였다.
chunked 인코딩 적용 시 Swagger UI에서 에러가 발생할 수 있다.
chunked 인코딩은 HTTP 프로토콜에서 사용되는 전송 코딩 방식 중 하나인데, 이 방식은 서버에서 전송할 데이터의 크기를 미리 알 수 없는 경우에 유용하게 사용한다. 그러나 Swagger UI와 결합하여 사용할 때, 요청 혹은 응답 본문의 크기가 일정 크기 이상인 경우 에러가 발생하곤 했다. 따라서 요청 혹은 응답 헤더에 Transfer-Encoding을 제거하거나 다른 방법으로 우회하여 해결해야 했다.
