Django Swagger 문서에 Custom JS 플러그인 추가하기

아니 이 필터가 왜이래

 

협업을 위한 Swagger 문서가 있다.사내에선 `drf-spectacular` 모듈을 사용하고 있었는데, 굉장히 불편한 점이 있었다.

 

 

API의 Tag로 `KAKAO` 로 설정해놓은 API가 보이질 않는다.

`kakao` 든, `KAKAO` 든, 다 필터링 돼야 하는 것 아닌가라는 의문이 있었는데,해당 키워드를 오픈채팅방에 물어보니 지원하지 않는 기능이라고 하셨다.

 

swagger setting으로 가져오는 번들 버전 및 옵션에 따라 기능을 이용할 수 있는데

이런 필터링 관련 기능은 제공하지 않는 것으로 보인다

 

관련 링크

https://github.com/swagger-api/swagger-ui/issues/8143https://github.com/swagger-api/swagger-ui/pull/6851

 

 

그래서,

Django에서 Swagger의 url을 설정할 때 SpectacularSwaggerView를 사용하는 것을 보고

해당 View에 대해서 알아보려고 했는데 여기서 방법을 찾았다고 생각했다.

class SpectacularSwaggerView(APIView):
    renderer_classes = [TemplateHTMLRenderer]
    permission_classes = spectacular_settings.SERVE_PERMISSIONS
    authentication_classes = AUTHENTICATION_CLASSES
    url_name: str = 'schema'
    url: Optional[str] = None
    template_name: str = 'drf_spectacular/swagger_ui.html'
    template_name_js: str = 'drf_spectacular/swagger_ui.js' # 찾았다 요놈
    title: str = spectacular_settings.TITLE

 

스웨거 템플릿의 자바스크립트는 View에서 따로 지정이 가능한 것으로 보인다.

 

# 해당 View를 상속해주고 `template_name_js`만 재정의
class CustomSwaggerSpectacularSwaggerView(SpectacularSwaggerView):
    template_name_js = "custom_swagger_ui.js"
    

# django settings의 urls.py 내에서 swagger url 재정의
from utils.custom_drf_spectacular import (
    CustomSwaggerSpectacularSwaggerView as SpectacularSwaggerView,
)


urlpatterns = [
	path(
            "swagger/",
            SpectacularSwaggerView.as_view(url_name="schema-json"),
            name="swagger-ui",
        )
]

 

 

기존 `swagger_ui.js` 파일을 그대로 가져와서 `templates` 폴더에 넣고 아래 코드 삽입

 

...

const AdvancedFilterPlugin = function (system) {
    return {
        fn: {
            opsFilter: function (taggedOps, phrase) {
                phrase = phrase.toLowerCase();
                var normalTaggedOps = JSON.parse(JSON.stringify(taggedOps));

                for (const [tagObj, value] of Object.entries(normalTaggedOps)) {
                    const operations = value.operations;
                    let i = operations.length;

                    while (i--) {
                        const operation = operations[i].operation;
                        const parameters = (operation.parameters || []).map(param => JSON.stringify(param)).join('').toLowerCase();
                        const responses = (operation.responses || {}).toString().toLowerCase();
                        const requestBody = (operation.requestBody || {}).toString().toLowerCase();

                        if (
                            operations[i].path.toLowerCase().includes(phrase) ||
                            (operation.summary && operation.summary.toLowerCase().includes(phrase)) ||
                            (operation.description && operation.description.toLowerCase().includes(phrase)) ||
                            parameters.includes(phrase) ||
                            responses.includes(phrase) ||
                            requestBody.includes(phrase)
                        ) {
                            // Do nothing
                        } else {
                            operations.splice(i, 1);
                        }
                    }

                    if (operations.length === 0) {
                        delete normalTaggedOps[tagObj];
                    } else {
                        normalTaggedOps[tagObj].operations = operations;
                    }
                }

                return system.Im.fromJS(normalTaggedOps);
            }
        }
    };
};

...

const plugins = [AdvancedFilterPlugin,];

...

 

`plugins` 부분에 삽입한 `AdvancedFilterPlugin`을 Push

 

이후 스웨거를 확인해보면...

 

야호 !

 

정상적으로 작동한다.

여기서 description 내에 내용이 포함되는 것을 원치 않는다면 js 코드를 수정하면 될 것 같다.

 

참고 링크

https://stackoverflow.com/questions/76931065/custom-swagger-ui-filter-plugin-opsfilter-in-a-net-core-app