Browse Source

๐ŸŒ Add Korean translation for `docs/ko/docs/how-to/configure-swagger-ui.md` (#12898)

pull/13018/head
nahyunkeem 4 months ago
committed by GitHub
parent
commit
49efaa5b7e
No known key found for this signature in database GPG Key ID: B5690EEEBB952194
  1. 70
      docs/ko/docs/how-to/configure-swagger-ui.md

70
docs/ko/docs/how-to/configure-swagger-ui.md

@ -0,0 +1,70 @@
# Swagger UI ๊ตฌ์„ฑ
์ถ”๊ฐ€์ ์ธ <a href="https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/" class="external-link" target="_blank">Swagger UI ๋งค๊ฐœ๋ณ€์ˆ˜</a>๋ฅผ ๊ตฌ์„ฑํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค.
๊ตฌ์„ฑ์„ ํ•˜๋ ค๋ฉด, `FastAPI()` ์•ฑ ๊ฐ์ฒด๋ฅผ ์ƒ์„ฑํ•  ๋•Œ ๋˜๋Š” `get_swagger_ui_html()` ํ•จ์ˆ˜์— `swagger_ui_parameters` ์ธ์ˆ˜๋ฅผ ์ „๋‹ฌํ•˜์‹ญ์‹œ์˜ค.
`swagger_ui_parameters`๋Š” Swagger UI์— ์ง์ ‘ ์ „๋‹ฌ๋œ ๊ตฌ์„ฑ์„ ํฌํ•จํ•˜๋Š” ๋”•์…”๋„ˆ๋ฆฌ๋ฅผ ๋ฐ›์Šต๋‹ˆ๋‹ค.
FastAPI๋Š” ์ด ๊ตฌ์„ฑ์„ **JSON** ํ˜•์‹์œผ๋กœ ๋ณ€ํ™˜ํ•˜์—ฌ JavaScript์™€ ํ˜ธํ™˜๋˜๋„๋ก ํ•ฉ๋‹ˆ๋‹ค. ์ด๋Š” Swagger UI์—์„œ ํ•„์š”๋กœ ํ•˜๋Š” ํ˜•์‹์ž…๋‹ˆ๋‹ค.
## ๊ตฌ๋ฌธ ๊ฐ•์กฐ ๋น„ํ™œ์„ฑํ™”
์˜ˆ๋ฅผ ๋“ค์–ด, Swagger UI์—์„œ ๊ตฌ๋ฌธ ๊ฐ•์กฐ ๊ธฐ๋Šฅ์„ ๋น„ํ™œ์„ฑํ™”ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค.
์„ค์ •์„ ๋ณ€๊ฒฝํ•˜์ง€ ์•Š์œผ๋ฉด, ๊ธฐ๋ณธ์ ์œผ๋กœ ๊ตฌ๋ฌธ ๊ฐ•์กฐ ๊ธฐ๋Šฅ์ด ํ™œ์„ฑํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค:
<img src="/img/tutorial/extending-openapi/image02.png">
๊ทธ๋Ÿฌ๋‚˜ `syntaxHighlight`๋ฅผ `False`๋กœ ์„ค์ •ํ•˜์—ฌ ๊ตฌ๋ฌธ ๊ฐ•์กฐ ๊ธฐ๋Šฅ์„ ๋น„ํ™œ์„ฑํ™”ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค:
{* ../../docs_src/configure_swagger_ui/tutorial001.py hl[3] *}
...๊ทธ๋Ÿผ Swagger UI์—์„œ ๋” ์ด์ƒ ๊ตฌ๋ฌธ ๊ฐ•์กฐ ๊ธฐ๋Šฅ์ด ํ‘œ์‹œ๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค:
<img src="/img/tutorial/extending-openapi/image03.png">
## ํ…Œ๋งˆ ๋ณ€๊ฒฝ
๋™์ผํ•œ ๋ฐฉ์‹์œผ๋กœ `"syntaxHighlight.theme"` ํ‚ค๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ๊ตฌ๋ฌธ ๊ฐ•์กฐ ํ…Œ๋งˆ๋ฅผ ์„ค์ •ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค (์ค‘๊ฐ„์— ์ ์ด ํฌํ•จ๋œ ๊ฒƒ์„ ์ฐธ๊ณ ํ•˜์‹ญ์‹œ์˜ค).
{* ../../docs_src/configure_swagger_ui/tutorial002.py hl[3] *}
์ด ์„ค์ •์€ ๊ตฌ๋ฌธ ๊ฐ•์กฐ ์ƒ‰์ƒ ํ…Œ๋งˆ๋ฅผ ๋ณ€๊ฒฝํ•ฉ๋‹ˆ๋‹ค:
<img src="/img/tutorial/extending-openapi/image04.png">
## ๊ธฐ๋ณธ Swagger UI ๋งค๊ฐœ๋ณ€์ˆ˜ ๋ณ€๊ฒฝ
FastAPI๋Š” ๋Œ€๋ถ€๋ถ„์˜ ์‚ฌ์šฉ ์‚ฌ๋ก€์— ์ ํ•ฉํ•œ ๋ช‡ ๊ฐ€์ง€ ๊ธฐ๋ณธ ๊ตฌ์„ฑ ๋งค๊ฐœ๋ณ€์ˆ˜๋ฅผ ํฌํ•จํ•˜๊ณ  ์žˆ์Šต๋‹ˆ๋‹ค.
๊ธฐ๋ณธ ๊ตฌ์„ฑ์—๋Š” ๋‹ค์Œ์ด ํฌํ•จ๋ฉ๋‹ˆ๋‹ค:
{* ../../fastapi/openapi/docs.py ln[8:23] hl[17:23] *}
`swagger_ui_parameters` ์ธ์ˆ˜์— ๋‹ค๋ฅธ ๊ฐ’์„ ์„ค์ •ํ•˜์—ฌ ์ด๋Ÿฌํ•œ ๊ธฐ๋ณธ๊ฐ’ ์ค‘ ์ผ๋ถ€๋ฅผ ์žฌ์ •์˜ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค.
์˜ˆ๋ฅผ ๋“ค์–ด, `deepLinking`์„ ๋น„ํ™œ์„ฑํ™”ํ•˜๋ ค๋ฉด `swagger_ui_parameters`์— ๋‹ค์Œ ์„ค์ •์„ ์ „๋‹ฌํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค:
{* ../../docs_src/configure_swagger_ui/tutorial003.py hl[3] *}
## ๊ธฐํƒ€ Swagger UI ๋งค๊ฐœ๋ณ€์ˆ˜
์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ๋Š” ๋‹ค๋ฅธ ๋ชจ๋“  ๊ตฌ์„ฑ ์˜ต์…˜์„ ํ™•์ธํ•˜๋ ค๋ฉด, Swagger UI ๋งค๊ฐœ๋ณ€์ˆ˜์— ๋Œ€ํ•œ ๊ณต์‹ <a href="https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/" class="external-link" target="_blank">๋ฌธ์„œ</a>๋ฅผ ์ฐธ์กฐํ•˜์‹ญ์‹œ์˜ค.
## JavaScript ์ „์šฉ ์„ค์ •
Swagger UI๋Š” **JavaScript ์ „์šฉ** ๊ฐ์ฒด(์˜ˆ: JavaScript ํ•จ์ˆ˜)๋กœ ๋‹ค๋ฅธ ๊ตฌ์„ฑ์„ ํ—ˆ์šฉํ•˜๊ธฐ๋„ ํ•ฉ๋‹ˆ๋‹ค.
FastAPI๋Š” ์ด๋Ÿฌํ•œ JavaScript ์ „์šฉ `presets` ์„ค์ •์„ ํฌํ•จํ•˜๊ณ  ์žˆ์Šต๋‹ˆ๋‹ค:
```JavaScript
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIBundle.SwaggerUIStandalonePreset
]
```
์ด๋“ค์€ ๋ฌธ์ž์—ด์ด ์•„๋‹Œ **JavaScript** ๊ฐ์ฒด์ด๋ฏ€๋กœ Python ์ฝ”๋“œ์—์„œ ์ง์ ‘ ์ „๋‹ฌํ•  ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค.
์ด์™€ ๊ฐ™์€ JavaScript ์ „์šฉ ๊ตฌ์„ฑ์„ ์‚ฌ์šฉํ•ด์•ผ ํ•˜๋Š” ๊ฒฝ์šฐ, ์œ„์˜ ๋ฐฉ๋ฒ• ์ค‘ ํ•˜๋‚˜๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ๋ชจ๋“  Swagger UI ๊ฒฝ๋กœ ์ž‘์—…์„ ์žฌ์ •์˜ํ•˜๊ณ  ํ•„์š”ํ•œ JavaScript๋ฅผ ์ˆ˜๋™์œผ๋กœ ์ž‘์„ฑํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค.
Loadingโ€ฆ
Cancel
Save