DRF Spectacular에서 Swagger 파라미터 순서 변경하기

Django 프로젝트에서 drf-spectacular을 사용해 Swagger 문서를 작성할 때, OpenApiParameter의 순서가 내가 작성한 순서가 아니라 name 기준으로 정렬되는 문제가 있었습니다. 이를 해결하는 과정을 정리해 보겠습니다.

---

1. 문제 상황

Swagger 문서에서 API의 파라미터는 기본적으로 name 기준으로 정렬됩니다. 하지만 사용자가 원하는 대로 순서를 지정하고 싶을 때가 있습니다. 예를 들어, 아래처럼 파라미터를 정의했다고 가정해 보겠습니다.

from drf_spectacular.utils import OpenApiParameter, extend_schema

@extend_schema(
    parameters=[
        OpenApiParameter("user_id", type=int, description="유저 ID"),
        OpenApiParameter("date", type=str, description="조회 날짜"),
    ]
)
def my_api_view(request):
    pass

위 코드는 user_id → date 순서로 작성되었지만, 실제 Swagger 문서에서는 date → user_id 순서로 정렬되는 문제가 발생합니다.

---

2. 해결 과정

2.1 구글링을 통한 문제 탐색

처음에는 drf-spectacular 공식 문서에서 @extend_schema의 옵션을 찾아보았지만, 파라미터 순서를 직접 조정하는 방법은 없었습니다. 따라서 추가적인 검색이 필요했습니다.

구글에서 "drf-spectacular parameter order"로 검색한 결과, 아래의 GitHub 이슈를 발견했습니다.

https://github.com/tfranzel/drf-spectacular/issues/281

Request: Ability to disable sorting of parameters · Issue #281 · tfranzel/drf-spectacular

이슈 내용을 확인해 보니 drf-spectacular 내부적으로 name 기준으로 정렬하는 코드가 있었습니다.

2.2 openapi.py 내부 코드 분석

이제 drf-spectacular의 openapi.py 파일에서 _get_parameters 함수를 찾아보았습니다.

위 코드에서 name 기준으로 정렬하는 것을 확인할 수 있었습니다.

2.3 SPECTACULAR_SETTINGS 수정

해당 정렬을 비활성화하려면 SORT_OPERATION_PARAMETERS 설정을 변경해야 합니다.

기본 설정은 SPECTACULAR_DEFAULTS에서 정의되며, True로 되어 있습니다.

이를 False로 설정하면 파라미터가 작성된 순서대로 유지됩니다.

 

---

3. 적용 결과

설정을 변경한 후 Swagger 문서를 다시 확인해 보니, 작성한 순서 그대로 파라미터가 표시되는 것을 확인할 수 있었습니다. 

변경 전 (기본 설정)

변경 후 (SORT_OPERATION_PARAMETERS = False 적용)

---

4. 정리

✅ drf-spectacular은 기본적으로 name 기준으로 파라미터를 정렬한다.
✅ SORT_OPERATION_PARAMETERS 옵션을 False로 설정하면 작성한 순서대로 유지된다.
✅ settings.py에서 SPECTACULAR_SETTINGS을 수정하여 적용할 수 있다.

이제 원하는 대로 API 문서의 파라미터 순서를 조정할 수 있습니다.