Swagger UI 구성하기

Swagger UI 구성하기 (Configure Swagger UI)

Swagger UI에는 몇 가지 추가적인 Swagger UI 파라미터 를 구성할 수 있어요.

이를 구성하려면 FastAPI() 앱 객체를 만들 때 swagger_ui_parameters 인자를 넘기거나, get_swagger_ui_html() 함수에 넘기면 돼요.

swagger_ui_parameters는 Swagger UI에 직접 전달되는 구성들의 딕셔너리를 받아요.

FastAPI는 그 구성들을 JSON으로 변환해서 JavaScript와 호환되게 만들어요. Swagger UI가 필요로 하는 것이 그거거든요.

출처: 공식문서

문법 하이라이팅 비활성화하기

예를 들어, Swagger UI에서 문법 하이라이팅(syntax highlighting)을 끌 수 있어요.

설정을 바꾸지 않으면 기본적으로 문법 하이라이팅이 켜져 있어요.

하지만 syntaxHighlight를 False로 설정하면 끌 수 있어요:

from fastapi import FastAPI

app = FastAPI(swagger_ui_parameters={"syntaxHighlight": False})


@app.get("/users/{username}")
async def read_user(username: str):
    return {"message": f"Hello {username}"}

...그러면 Swagger UI는 더 이상 문법 하이라이팅을 보여주지 않아요.

테마 바꾸기

마찬가지로 "syntaxHighlight.theme" 키(가운데에 점이 있다는 점에 주의하세요)로 문법 하이라이팅 테마를 설정할 수 있어요:

from fastapi import FastAPI

app = FastAPI(swagger_ui_parameters={"syntaxHighlight": {"theme": "obsidian"}})


@app.get("/users/{username}")
async def read_user(username: str):
    return {"message": f"Hello {username}"}

이 구성은 문법 하이라이팅의 색상 테마를 바꿔줘요.

기본 Swagger UI 파라미터 변경하기

FastAPI에는 대부분의 사용 사례에 적합한 몇 가지 기본 구성 파라미터가 포함돼 있어요.

이 기본 구성들은 다음과 같아요:

swagger_ui_default_parameters = {
    "dom_id": "#swagger-ui",
    "layout": "BaseLayout",
    "deepLinking": True,
    "showExtensions": True,
    "showCommonExtensions": True,
}

swagger_ui_parameters 인자에서 다른 값을 설정해서 이 중 아무거나 오버라이드할 수 있어요.

예를 들어 deepLinking을 비활성화하려면 swagger_ui_parameters에 이 설정을 넘기면 돼요:

from fastapi import FastAPI

app = FastAPI(swagger_ui_parameters={"deepLinking": False})


@app.get("/users/{username}")
async def read_user(username: str):
    return {"message": f"Hello {username}"}

기타 Swagger UI 파라미터

사용할 수 있는 다른 모든 가능한 구성들을 보려면, 공식 Swagger UI 파라미터 문서 를 읽어보세요.

JavaScript 전용 설정

Swagger UI는 다른 구성들도 JavaScript 전용 객체(예: JavaScript 함수)로 허용해요.

FastAPI에는 이런 JavaScript 전용 presets 설정도 포함돼 있어요:

presets: [
    SwaggerUIBundle.presets.apis,
    SwaggerUIBundle.SwaggerUIStandalonePreset
]

이것들은 JavaScript 객체이지 문자열이 아니어서, Python 코드에서 직접 전달할 수 없어요.

이런 JavaScript 전용 구성을 사용해야 한다면, 위의 방법 중 하나를 쓰면 돼요. 전체 Swagger UI path operation을 오버라이드하고 필요한 JavaScript를 직접 작성하세요.

Swagger UI 구성하기