🌐 Add Korean translation for Tutorial - Path Parameters (#2355)

docs/ko/docs/tutorial/path-params.md

@@ -0,0 +1,244 @@
+# 경로 매개변수
+
+파이썬 포맷 문자열이 사용하는 동일한 문법으로 "매개변수" 또는 "변수"를 경로에 선언할 수 있습니다:
+
+```Python hl_lines="6-7"
+{!../../../docs_src/path_params/tutorial001.py!}
+```
+
+경로 매개변수 `item_id`의 값은 함수의 `item_id` 인자로 전달됩니다.
+
+그래서 이 예제를 실행하고 <a href="http://127.0.0.1:8000/items/foo" class="external-link" target="_blank">http://127.0.0.1:8000/items/foo</a>로 이동하면, 다음 응답을 볼 수 있습니다:
+
+```JSON
+{"item_id":"foo"}
+```
+
+## 타입이 있는 매개변수
+
+파이썬 표준 타입 어노테이션을 사용하여 함수에 있는 경로 매개변수의 타입을 선언할 수 있습니다:
+
+```Python hl_lines="7"
+{!../../../docs_src/path_params/tutorial002.py!}
+```
+
+지금과 같은 경우, `item_id`는 `int`로 선언 되었습니다.
+
+!!! check "확인"
+    이 기능은 함수 내에서 오류 검사, 자동완성 등을 편집기를 지원합니다
+
+## 데이터 <abbr title="다음으로도 알려져 있습니다: 직렬화, 파싱, 마샬링">변환</abbr>
+
+이 예제를 실행하고 <a href="http://127.0.0.1:8000/items/3" class="external-link" target="_blank">http://127.0.0.1:8000/items/3</a>을 열면, 다음 응답을 볼 수 있습니다:
+
+```JSON
+{"item_id":3}
+```
+
+!!! check "확인"
+    함수가 받은(반환도 하는) 값은 문자열 `"3"`이 아니라 파이썬 `int` 형인 `3`입니다.
+
+    즉, 타입 선언을 하면 **FastAPI**는 자동으로 요청을 <abbr title="HTTP 요청에서 전달되는 문자열을 파이썬 데이터로 변환">"파싱"</abbr>합니다.
+
+## 데이터 검증
+
+하지만 브라우저에서 <a href="http://127.0.0.1:8000/items/foo" class="external-link" target="_blank">http://127.0.0.1:8000/items/foo</a>로 이동하면, 멋진 HTTP 오류를 볼 수 있습니다:
+
+```JSON
+{
+    "detail": [
+        {
+            "loc": [
+                "path",
+                "item_id"
+            ],
+            "msg": "value is not a valid integer",
+            "type": "type_error.integer"
+        }
+    ]
+}
+```
+
+경로 매개변수 `item_id`는 `int`가 아닌 `"foo"` 값이기 때문입니다.
+
+`int` 대신 `float`을 전달하면 동일한 오류가 나타납니다: <a href="http://127.0.0.1:8000/items/4.2" class="external-link" target="_blank">http://127.0.0.1:8000/items/4.2</a>
+
+!!! check "확인"
+    즉, 파이썬 타입 선언을 하면 **FastAPI**는 데이터 검증을 합니다.
+
+    오류는 검증을 통과하지 못한 지점도 정확하게 명시합니다.
+
+    이는 API와 상호 작용하는 코드를 개발하고 디버깅하는 데 매우 유용합니다.
+
+## 문서화
+
+그리고 브라우저에서 <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>를 열면, 다음과 같이 자동 대화식 API 문서를 볼 수 있습니다:
+
+<img src="/img/tutorial/path-params/image01.png">
+
+!!! check "확인"
+    다시 한번, 그저 파이썬 타입 선언을 하기만 하면 **FastAPI**는 자동 대화식 API 문서(Swagger UI 통합)를 제공합니다.
+
+    경로 매개변수는 정수형으로 선언됐음을 주목하세요.
+
+## 표준 기반의 이점, 대체 문서화
+
+그리고 생성된 스키마는 <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md" class="external-link" target="_blank">OpenAPI</a> 표준에서 나온 것이기 때문에 호환되는 도구가 많이 있습니다.
+
+이 덕분에 **FastAPI**는 <a href="http://127.0.0.1:8000/redoc" class="external-link" target="_blank">http://127.0.0.1:8000/redoc</a>로 접속할 수 있는 (ReDoc을 사용하는) 대체 API 문서를 제공합니다:
+
+<img src="/img/tutorial/path-params/image02.png">
+
+이와 마찬가지로 호환되는 도구가 많이 있습니다. 다양한 언어에 대한 코드 생성 도구를 포함합니다.
+
+## Pydantic
+
+모든 데이터 검증은 <a href="https://pydantic-docs.helpmanual.io/" class="external-link" target="_blank">Pydantic</a>에 의해 내부적으로 수행되므로 이로 인한 모든 이점을 얻을 수 있습니다. 여러분은 관리를 잘 받고 있음을 느낄 수 있습니다.
+
+`str`, `float`, `bool`과 다른 복잡한 데이터 타입 선언을 할 수 있습니다.
+
+이 중 몇 가지는 자습서의 다음 장에서 살펴봅니다.
+
+## 순서 문제
+
+*경로 동작*을 만들때 고정 경로를 갖고 있는 상황들을 맞닦뜨릴 수 있습니다.
+
+`/users/me`처럼, 현재 사용자의 데이터를 가져온다고 합시다.
+
+사용자 ID를 이용해 특정 사용자의 정보를 가져오는 경로 `/users/{user_id}`도 있습니다.
+
+*경로 동작*은 순차적으로 평가되기 때문에 `/users/{user_id}` 이전에 `/users/me`를 먼저 선언해야 합니다:
+
+```Python hl_lines="6  11"
+{!../../../docs_src/path_params/tutorial003.py!}
+```
+
+그렇지 않으면 `/users/{user_id}`는 매개변수 `user_id`의 값을 `"me"`라고 "생각하여" `/users/me`도 연결합니다.
+
+## 사전정의 값
+
+만약 *경로 매개변수*를 받는 *경로 동작*이 있지만, 유효하고 미리 정의할 수 있는 *경로 매개변수* 값을 원한다면 파이썬 표준 <abbr title="열거형(Enumeration)">`Enum`</abbr>을 사용할 수 있습니다.
+
+### `Enum` 클래스 생성
+
+`Enum`을 임포트하고 `str`과 `Enum`을 상속하는 서브 클래스를 만듭니다.
+
+`str`을 상속함으로써 API 문서는 값이 `string` 형이어야 하는 것을 알게 되고 제대로 렌더링 할 수 있게 됩니다.
+
+고정값으로 사용할 수 있는 유효한 클래스 어트리뷰트를 만듭니다:
+
+```Python hl_lines="1  6-9"
+{!../../../docs_src/path_params/tutorial005.py!}
+```
+
+!!! info "정보"
+    <a href="https://docs.python.org/3/library/enum.html" class="external-link" target="_blank">열거형(또는 enums)</a>은 파이썬 버전 3.4 이후로 사용가능합니다.
+
+!!! tip "팁"
+    혹시 헷갈린다면, "AlexNet", "ResNet", 그리고 "LeNet"은 그저 기계 학습 <abbr title="기술적으로 정확히는 딥 러닝 모델 구조">모델</abbr>들의 이름입니다.
+
+### *경로 매개변수* 선언
+
+생성한 열거형 클래스(`ModelName`)를 사용하는 타입 어노테이션으로 *경로 매개변수*를 만듭니다:
+
+```Python hl_lines="16"
+{!../../../docs_src/path_params/tutorial005.py!}
+```
+
+### 문서 확인
+
+*경로 매개변수*에 사용할 수 있는 값은 미리 정의되어 있으므로 대화형 문서에서 멋지게 표시됩니다:
+
+<img src="/img/tutorial/path-params/image03.png">
+
+### 파이썬 *열거형*으로 작업하기
+
+*경로 매개변수*의 값은 *열거형 멤버*가 됩니다.
+
+#### *열거형 멤버* 비교
+
+열거체 `ModelName`의 *열거형 멤버*를 비교할 수 있습니다:
+
+```Python hl_lines="17"
+{!../../../docs_src/path_params/tutorial005.py!}
+```
+
+#### *열거형 값* 가져오기
+
+`model_name.value` 또는 일반적으로 `your_enum_member.value`를 이용하여 실제값(지금의 경우 `str`)을 가져올 수 있습니다:
+
+```Python hl_lines="20"
+{!../../../docs_src/path_params/tutorial005.py!}
+```
+
+!!! tip "팁"
+    `ModelName.lenet.value`로도 값 `"lenet"`에 접근할 수 있습니다.
+
+#### *열거형 멤버* 반환
+
+*경로 동작*에서 중첩 JSON 본문(예: `dict`) 역시 *열거형 멤버*를 반환할 수 있습니다.
+
+클라이언트에 반환하기 전에 해당 값(이 경우 문자열)으로 변환됩니다:
+
+```Python hl_lines="18  21  23"
+{!../../../docs_src/path_params/tutorial005.py!}
+```
+
+클라이언트는 아래의 JSON 응답을 얻습니다:
+
+```JSON
+{
+  "model_name": "alexnet",
+  "message": "Deep Learning FTW!"
+}
+```
+
+## 경로를 포함하는 경로 매개변수
+
+`/files/{file_path}`가 있는 *경로 동작*이 있다고 해봅시다.
+
+그런데 여러분은 `home/johndoe/myfile.txt`처럼 *path*에 들어있는 `file_path` 자체가 필요합니다.
+
+따라서 해당 파일의 URL은 다음처럼 됩니다: `/files/home/johndoe/myfile.txt`.
+
+### OpenAPI 지원
+
+테스트와 정의가 어려운 시나리오로 이어질 수 있으므로 OpenAPI는 *경로*를 포함하는 *경로 매개변수*를 내부에 선언하는 방법을 지원하지 않습니다.
+
+그럼에도 Starlette의 내부 도구중 하나를 사용하여 **FastAPI**에서는 할 수 있습니다.
+
+매개변수에 경로가 포함되어야 한다는 문서를 추가하지 않아도 문서는 계속 작동합니다.
+
+### 경로 변환기
+
+Starlette에서 직접 옵션을 사용하면 다음과 같은 URL을 사용하여 *path*를 포함하는 *경로 매개변수*를 선언 할 수 있습니다:
+
+```
+/files/{file_path:path}
+```
+
+이러한 경우 매개변수의 이름은 `file_path`이고 마지막 부분 `:path`는 매개변수가 *경로*와 일치해야함을 알려줍니다.
+
+그러므로 다음과 같이 사용할 수 있습니다:
+
+```Python hl_lines="6"
+{!../../../docs_src/path_params/tutorial004.py!}
+```
+
+!!! tip "팁"
+    매개변수가 `/home/johndoe/myfile.txt`를 갖고 있어 슬래시로 시작(`/`)해야 할 수 있습니다.
+
+    이 경우 URL은: `/files//home/johndoe/myfile.txt`이며 `files`과 `home` 사이에 이중 슬래시(`//`)가 생깁니다.
+
+## 요약
+
+**FastAPI**과 함께라면 짧고 직관적인 표준 파이썬 타입 선언을 사용하여 다음을 얻을 수 있습니다:
+
+* 편집기 지원: 오류 검사, 자동완성 등
+* 데이터 "<abbr title="HTTP 요청에서 전달되는 문자열을 파이썬 데이터로 변환">파싱</abbr>"
+* 데이터 검증
+* API 주석(Annotation)과 자동 문서
+
+위 사항들을 그저 한번에 선언하면 됩니다.
+
+이는 (원래 성능과는 별개로) 대체 프레임워크와 비교했을 때 **FastAPI**의 주요 가시적 장점일 것입니다.

docs/ko/mkdocs.yml

@@ -53,6 +53,7 @@ nav:
 - 자습서 - 사용자 안내서:
   - tutorial/index.md
   - tutorial/first-steps.md
+  - tutorial/path-params.md
   - tutorial/header-params.md
 markdown_extensions:
 - toc: