Browse Source

๐ŸŒ Add Korean translation for `docs/ko/docs/how-to/conditional-openapi.md` (#12731)

pull/12794/head
sptcnl 5 months ago
committed by GitHub
parent
commit
2fcae5f108
No known key found for this signature in database GPG Key ID: B5690EEEBB952194
  1. 61
      docs/ko/docs/how-to/conditional-openapi.md

61
docs/ko/docs/how-to/conditional-openapi.md

@ -0,0 +1,61 @@
# ์กฐ๊ฑด๋ถ€์ ์ธ OpenAPI
ํ•„์š”ํ•œ ๊ฒฝ์šฐ, ์„ค์ • ๋ฐ ํ™˜๊ฒฝ ๋ณ€์ˆ˜๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ํ™˜๊ฒฝ์— ๋”ฐ๋ผ ์กฐ๊ฑด๋ถ€๋กœ OpenAPI๋ฅผ ๊ตฌ์„ฑํ•˜๊ณ  ์™„์ „ํžˆ ๋น„ํ™œ์„ฑํ™”ํ•  ์ˆ˜๋„ ์žˆ์Šต๋‹ˆ๋‹ค.
## ๋ณด์•ˆ, API ๋ฐ docs์— ๋Œ€ํ•ด์„œ
ํ”„๋กœ๋•์…˜์—์„œ, ๋ฌธ์„œํ™”๋œ ์‚ฌ์šฉ์ž ์ธํ„ฐํŽ˜์ด์Šค(UI)๋ฅผ ์ˆจ๊ธฐ๋Š” ๊ฒƒ์ด API๋ฅผ ๋ณดํ˜ธํ•˜๋Š” ๋ฐฉ๋ฒ•์ด *๋˜์–ด์„œ๋Š” ์•ˆ ๋ฉ๋‹ˆ๋‹ค*.
์ด๋Š” API์— ์ถ”๊ฐ€์ ์ธ ๋ณด์•ˆ์„ ์ œ๊ณตํ•˜์ง€ ์•Š์œผ๋ฉฐ, *๊ฒฝ๋กœ ์ž‘์—…*์€ ์—ฌ์ „ํžˆ ๋™์ผํ•œ ์œ„์น˜์—์„œ ์‚ฌ์šฉ ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค.
์ฝ”๋“œ์— ๋ณด์•ˆ ๊ฒฐํ•จ์ด ์žˆ๋‹ค๋ฉด, ๊ทธ ๊ฒฐํ•จ์€ ์—ฌ์ „ํžˆ ์กด์žฌํ•  ๊ฒƒ์ž…๋‹ˆ๋‹ค.
๋ฌธ์„œ๋ฅผ ์ˆจ๊ธฐ๋Š” ๊ฒƒ์€ API์™€ ์ƒํ˜ธ์ž‘์šฉํ•˜๋Š” ๋ฐฉ๋ฒ•์„ ์ดํ•ดํ•˜๊ธฐ ์–ด๋ ต๊ฒŒ ๋งŒ๋“ค๋ฉฐ, ํ”„๋กœ๋•์…˜์—์„œ ๋””๋ฒ„๊น…์„ ๋” ์–ด๋ ต๊ฒŒ ๋งŒ๋“ค ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ์ด๋Š” ๋‹จ์ˆœํžˆ <a href="https://en.wikipedia.org/wiki/Security_through_obscurity" class="external-link" target="_blank">'๋ชจํ˜ธ์„ฑ์— ์˜ํ•œ ๋ณด์•ˆ'</a>์˜ ํ•œ ํ˜•ํƒœ๋กœ ๊ฐ„์ฃผ๋  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค.
API๋ฅผ ๋ณดํ˜ธํ•˜๊ณ  ์‹ถ๋‹ค๋ฉด, ์˜ˆ๋ฅผ ๋“ค์–ด ๋‹ค์Œ๊ณผ ๊ฐ™์€ ๋” ๋‚˜์€ ๋ฐฉ๋ฒ•๋“ค์ด ์žˆ์Šต๋‹ˆ๋‹ค:
* ์š”์ฒญ ๋ณธ๋ฌธ๊ณผ ์‘๋‹ต์— ๋Œ€ํ•ด ์ž˜ ์ •์˜๋œ Pydantic ๋ชจ๋ธ์„ ์‚ฌ์šฉํ•˜๋„๋ก ํ•˜์„ธ์š”.
* ์ข…์†์„ฑ์„ ์‚ฌ์šฉํ•˜์—ฌ ํ•„์š”ํ•œ ๊ถŒํ•œ๊ณผ ์—ญํ• ์„ ๊ตฌ์„ฑํ•˜์„ธ์š”.
* ํ‰๋ฌธ ๋น„๋ฐ€๋ฒˆํ˜ธ๋ฅผ ์ ˆ๋Œ€ ์ €์žฅํ•˜์ง€ ๋ง๊ณ , ์˜ค์ง ์•”ํ˜ธํ™”๋œ ๋น„๋ฐ€๋ฒˆํ˜ธ๋งŒ ์ €์žฅํ•˜์„ธ์š”.
* Passlib๊ณผ JWT ํ† ํฐ๊ณผ ๊ฐ™์€ ์ž˜ ์•Œ๋ ค์ง„ ์•”ํ˜ธํ™” ๋„๊ตฌ๋“ค์„ ๊ตฌํ˜„ํ•˜๊ณ  ์‚ฌ์šฉํ•˜์„ธ์š”.
* ํ•„์š”ํ•œ ๊ณณ์— OAuth2 ๋ฒ”์œ„๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ๋” ์„ธ๋ถ„ํ™”๋œ ๊ถŒํ•œ ์ œ์–ด๋ฅผ ์ถ”๊ฐ€ํ•˜์„ธ์š”.
* ๋“ฑ๋“ฑ....
๊ทธ๋Ÿผ์—๋„ ๋ถˆ๊ตฌํ•˜๊ณ , ํŠน์ • ํ™˜๊ฒฝ(์˜ˆ: ํ”„๋กœ๋•์…˜)์—์„œ ๋˜๋Š” ํ™˜๊ฒฝ ๋ณ€์ˆ˜์˜ ์„ค์ •์— ๋”ฐ๋ผ API ๋ฌธ์„œ๋ฅผ ๋น„ํ™œ์„ฑํ™”ํ•ด์•ผ ํ•˜๋Š” ๋งค์šฐ ํŠน์ •ํ•œ ์‚ฌ์šฉ ์‚ฌ๋ก€๊ฐ€ ์žˆ์„ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค.
## ์„ค์ • ๋ฐ ํ™˜๊ฒฝ๋ณ€์ˆ˜์˜ ์กฐ๊ฑด๋ถ€ OpenAPI
๋™์ผํ•œ Pydantic ์„ค์ •์„ ์‚ฌ์šฉํ•˜์—ฌ ์ƒ์„ฑ๋œ OpenAPI ๋ฐ ๋ฌธ์„œ UI๋ฅผ ์‰ฝ๊ฒŒ ๊ตฌ์„ฑํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค.
์˜ˆ๋ฅผ ๋“ค์–ด:
{* ../../docs_src/conditional_openapi/tutorial001.py hl[6,11] *}
์—ฌ๊ธฐ์„œ `openapi_url` ์„ค์ •์„ ๊ธฐ๋ณธ๊ฐ’์ธ `"/openapi.json"`์œผ๋กœ ์„ ์–ธํ•ฉ๋‹ˆ๋‹ค.
๊ทธ๋Ÿฐ ๋’ค, ์šฐ๋ฆฌ๋Š” `FastAPI` ์•ฑ์„ ๋งŒ๋“ค ๋•Œ ๊ทธ๊ฒƒ์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค.
ํ™˜๊ฒฝ ๋ณ€์ˆ˜ `OPENAPI_URL`์„ ๋นˆ ๋ฌธ์ž์—ด๋กœ ์„ค์ •ํ•˜์—ฌ OpenAPI(๋ฌธ์„œ UI ํฌํ•จ)๋ฅผ ๋น„ํ™œ์„ฑํ™”ํ•  ์ˆ˜๋„ ์žˆ์Šต๋‹ˆ๋‹ค. ์˜ˆ๋ฅผ ๋“ค์–ด:
<div class="termy">
```console
$ OPENAPI_URL= uvicorn main:app
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
</div>
๊ทธ๋ฆฌ๊ณ  `/openapi.json`, `/docs` ๋˜๋Š” `/redoc`์˜ URL๋กœ ์ด๋™ํ•˜๋ฉด `404 Not Found`๋ผ๋Š” ์˜ค๋ฅ˜๊ฐ€ ๋‹ค์Œ๊ณผ ๊ฐ™์ด ํ‘œ์‹œ๋ฉ๋‹ˆ๋‹ค:
```JSON
{
"detail": "Not Found"
}
```
Loadingโ€ฆ
Cancel
Save