happyz
/
fastapi
mirror of https://github.com/tiangolo/fastapi.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

🌐 Update Korean translation for `docs/ko/docs/tutorial/first-steps.md`, `docs/ko/docs/tutorial/index.md`, `docs/ko/docs/tutorial/path-params.md`, and `docs/ko/docs/tutorial/query-params.md` (#4218)

This commit is contained in:
Soonho Kwon 2024-02-03 02:39:46 +09:00 committed by GitHub
parent 6f6e786979
commit d254e2f6ad
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 104 additions and 103 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

90
docs/ko/docs/tutorial/first-steps.md
View File

@ -1,12 +1,12 @@
# 첫걸음
가장 단순한 FastAPI 파일은 다음과 같이 보일 겁니다:
가장 단순한 FastAPI 파일은 다음과 같이 보일 것입니다:
```Python
{!../../../docs_src/first_steps/tutorial001.py!}
```
위를 `main.py`에 복사합니다.
위 코드를 `main.py`에 복사합니다.
라이브 서버를 실행합니다:
@ -29,9 +29,9 @@ $ uvicorn main:app --reload
* `main`: 파일 `main.py` (파이썬 "모듈").
* `app`: `main.py` 내부의 `app = FastAPI()` 줄에서 생성한 오브젝트.
* `--reload`: 코드 변경 후 서버 재시작. 개발에만 사용.
* `--reload`: 코드 변경 시 자동으로 서버 재시작. 개발 시에만 사용.
출력에 아래와 같은 줄이 있습니다:
출력되는 줄들 중에는 아래와 같은 내용이 있습니다:
```hl_lines="4"
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
@ -75,7 +75,7 @@ INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
#### API "스키마"
이 경우, <a href="https://github.com/OAI/OpenAPI-Specification" class="external-link" target="_blank">OpenAPI</a>는 API의 스키마를 어떻게 정의하는지 지시하는 규격입니다.
<a href="https://github.com/OAI/OpenAPI-Specification" class="external-link" target="_blank">OpenAPI</a>는 API의 스키마를 어떻게 정의하는지 지시하는 규격입니다.
이 스키마 정의는 API 경로, 가능한 매개변수 등을 포함합니다.
@ -87,13 +87,13 @@ INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
#### OpenAPI와 JSON 스키마
OpenAPI는 API에 대한 API 스키마를 정의합니다. 또한 이 스키마에는 JSON 데이터 스키마의 표준인 **JSON 스키마**를 사용하여 API에서 보내고 받은 데이터의 정의(또는 "스키마")를 포함합니다.
OpenAPI는 당신의 API에 대한 API 스키마를 정의합니다. 또한 이 스키마는 JSON 데이터 스키마의 표준인 **JSON 스키마**를 사용하여 당신의 API가 보내고 받는 데이터의 정의(또는 "스키마")를 포함합니다.
#### `openapi.json` 확인
가공되지 않은 OpenAPI 스키마가 어떻게 생겼는지 궁금하다면, FastAPI는 자동으로 API의 설명과 함께 JSON (스키마)를 생성합니다.
FastAPI는 자동으로 API의 설명과 함께 JSON (스키마)를 생성합니다.
여기에서 직접 볼 수 있습니다: <a href="http://127.0.0.1:8000/openapi.json" class="external-link" target="_blank">http://127.0.0.1:8000/openapi.json</a>.
가공되지 않은 OpenAPI 스키마가 어떻게 생겼는지 궁금하다면, 여기에서 직접 볼 수 있습니다: <a href="http://127.0.0.1:8000/openapi.json" class="external-link" target="_blank">http://127.0.0.1:8000/openapi.json</a>.
다음과 같이 시작하는 JSON을 확인할 수 있습니다:
@ -124,7 +124,7 @@ OpenAPI 스키마는 포함된 두 개의 대화형 문서 시스템을 제공
그리고 OpenAPI의 모든 것을 기반으로 하는 수십 가지 대안이 있습니다. **FastAPI**로 빌드한 애플리케이션에 이러한 대안을 쉽게 추가 할 수 있습니다.
API와 통신하는 클라이언트를 위해 코드를 자동으로 생성하는 데도 사용할 수 있습니다. 예로 프론트엔드, 모바일, IoT 애플리케이션이 있습니다.
API와 통신하는 클라이언트(프론트엔드, 모바일, IoT 애플리케이션 등)를 위해 코드를 자동으로 생성하는 데도 사용할 수 있습니다.
## 단계별 요약
@ -134,7 +134,7 @@ API와 통신하는 클라이언트를 위해 코드를 자동으로 생성하
{!../../../docs_src/first_steps/tutorial001.py!}
```
`FastAPI`는 API에 대한 모든 기능을 제공하는 파이썬 클래스입니다.
`FastAPI`는 당신의 API를 위한 모든 기능을 제공하는 파이썬 클래스입니다.
!!! note "기술 세부사항"
`FastAPI`는 `Starlette`를 직접 상속하는 클래스입니다.
@ -147,11 +147,11 @@ API와 통신하는 클라이언트를 위해 코드를 자동으로 생성하
{!../../../docs_src/first_steps/tutorial001.py!}
```
여기 있는 `app` 변수는 `FastAPI` 클래스의 "인스턴스"가 됩니다.
여기에서 `app` 변수는 `FastAPI` 클래스의 "인스턴스"가 됩니다.
이것은 모든 API를 생성하기 위한 상호작용의 주요 지점이 될 것입니다.
이것은 당신의 모든 API를 생성하기 위한 상호작용의 주요 지점이 될 것입니다.
이 `app`은 다음 명령에서 `uvicorn`이 참조하고 것과 동일합니다:
이 `app`은 다음 명령에서 `uvicorn`이 참조하고 있는 것과 동일합니다:
<div class="termy">
@ -181,11 +181,11 @@ $ uvicorn main:my_awesome_api --reload
</div>
### 3 단계: *경로 동작* 생성
### 3 단계: *경로 작동* 생성
#### 경로
여기서 "경로"는 첫 번째 `/`에서 시작하는 URL의 마지막 부분을 나타냅니다.
여기서 "경로"는 첫 번째 `/`부터 시작하는 URL의 뒷부분을 의미합니다.
그러므로 아래와 같은 URL에서:
@ -200,13 +200,13 @@ https://example.com/items/foo
```
!!! info "정보"
"경로"는 일반적으로 "앤드포인트" 또는 "라우트"라고도 불립니다.
"경로"는 일반적으로 "엔드포인트" 또는 "라우트"라고도 불립니다.
API를 빌드하는 동안 "경로"는 "관심사"와 "리소스"를 분리하는 주요 방법입니다.
API를 설계할 때 "경로"는 "관심사"와 "리소스"를 분리하기 위한 주요한 방법입니다.
#### 동작
#### 작동
여기서 "동작(Operation)"은 HTTP "메소드" 중 하나를 나타냅니다.
"작동(Operation)"은 HTTP "메소드" 중 하나를 나타냅니다.
다음 중 하나이며:
@ -215,7 +215,7 @@ API를 빌드하는 동안 "경로"는 "관심사"와 "리소스"를 분리하
* `PUT`
* `DELETE`
...이국적인 것들도 있습니다:
...흔히 사용되지 않는 것들도 있습니다:
* `OPTIONS`
* `HEAD`
@ -226,20 +226,20 @@ HTTP 프로토콜에서는 이러한 "메소드"를 하나(또는 이상) 사용
---
API를 빌드하는 동안 일반적으로 특정 행동을 수행하기 위해 특정 HTTP 메소드를 사용합니다.
API를 설계할 때 일반적으로 특정 행동을 수행하기 위해 특정 HTTP 메소드를 사용합니다.
일반적으로 다음을 사용합니다:
일반적으로 다음과 같습니다:
* `POST`: 데이터를 생성하기 위해.
* `GET`: 데이터를 읽기 위해.
* `PUT`: 데이터를 업데이트하기 위해.
* `PUT`: 데이터를 수정하기 위해.
* `DELETE`: 데이터를 삭제하기 위해.
그래서 OpenAPI에서는 각 HTTP 메소드들을 "동작"이라 부릅니다.
그래서 OpenAPI에서는 각 HTTP 메소드들을 "작동"이라 부릅니다.
이제부터 우리는 메소드를 "**동작**"이라고도 부를겁니다.
우리 역시 이제부터 메소드를 "**작동**"이라고 부를 것입니다.
#### *경로 동작 데코레이터* 정의
#### *경로 작동 데코레이터* 정의
```Python hl_lines="6"
{!../../../docs_src/first_steps/tutorial001.py!}
@ -248,26 +248,26 @@ API를 빌드하는 동안 일반적으로 특정 행동을 수행하기 위해
`@app.get("/")`은 **FastAPI**에게 바로 아래에 있는 함수가 다음으로 이동하는 요청을 처리한다는 것을 알려줍니다.
* 경로 `/`
* <abbr title="HTTP GET 메소드"><code>get</code> 동작</abbr> 사용
* <abbr title="HTTP GET 메소드"><code>get</code> 작동</abbr> 사용
!!! info "`@decorator` 정보"
이 `@something` 문법은 파이썬에서 "데코레이터"라 부릅니다.
함수 맨 위에 놓습니다. 마치 예쁜 장식용(Decorative) 모자처럼(개인적으로 이 용어가 여기서 유래한거 같습니다).
마치 예쁜 장식용(Decorative) 모자처럼(개인적으로 이 용어가 여기서 유래한 것 같습니다) 함수 맨 위에 놓습니다.
"데코레이터" 아래 있는 함수를 받고 그걸 이용해 무언가 합니다.
"데코레이터"는 아래 있는 함수를 받아 그것으로 무언가를 합니다.
우리의 경우, 이 데코레이터는 **FastAPI**에게 아래 함수가 **경로** `/`에 해당하는 `get` **동작**하라고 알려줍니다.
우리의 경우, 이 데코레이터는 **FastAPI**에게 아래 함수가 **경로** `/`의 `get` **작동**에 해당한다고 알려줍니다.
이것이 "**경로 동작 데코레이터**"입니다.
이것이 "**경로 작동 데코레이터**"입니다.
다른 동작도 쓸 수 있습니다:
다른 작동도 사용할 수 있습니다:
* `@app.post()`
* `@app.put()`
* `@app.delete()`
이국적인 것들도 있습니다:
흔히 사용되지 않는 것들도 있습니다:
* `@app.options()`
* `@app.head()`
@ -275,20 +275,20 @@ API를 빌드하는 동안 일반적으로 특정 행동을 수행하기 위해
* `@app.trace()`
!!! tip "팁"
각 동작(HTTP 메소드)을 원하는 대로 사용해도 됩니다.
각 작동(HTTP 메소드)을 원하는 대로 사용해도 됩니다.
**FastAPI**는 특정 의미를 강제하지 않습니다.
여기서 정보는 지침서일뿐 요구사항이 아닙니다.
여기서 정보는 지침서일뿐 강제사항이 아닙니다.
예를 들어 GraphQL을 사용할때 일반적으로 `POST` 동작만 사용하여 모든 행동을 수행합니다.
예를 들어 GraphQL을 사용하는 경우, 일반적으로 `POST` 작동만 사용하여 모든 행동을 수행합니다.
### 4 단계: **경로 동작 함수** 정의
### 4 단계: **경로 작동 함수** 정의
다음은 우리의 "**경로 동작 함수**"입니다:
다음은 우리의 "**경로 작동 함수**"입니다:
* **경로**: 는 `/`입니다.
* **동작**: 은 `get`입니다.
* **작동**: 은 `get`입니다.
* **함수**: 는 "데코레이터" 아래에 있는 함수입니다 (`@app.get("/")` 아래).
```Python hl_lines="7"
@ -297,13 +297,13 @@ API를 빌드하는 동안 일반적으로 특정 행동을 수행하기 위해
이것은 파이썬 함수입니다.
`GET` 동작을 사용하여 URL "`/`"에 대한 요청을 받을 때마다 **FastAPI**에 의해 호출됩니다.
URL "`/`"에 대한 `GET` 작동을 사용하는 요청을 받을 때마다 **FastAPI**에 의해 호출됩니다.
위의 경우 `async` 함수입니다.
위의 예시에서 이 함수는 `async`(비동기) 함수입니다.
---
`async def` 대신 일반 함수로 정의할 수 있습니다:
`async def`을 이용하는 대신 일반 함수로 정의할 수 있습니다:
```Python hl_lines="7"
{!../../../docs_src/first_steps/tutorial003.py!}
@ -322,12 +322,12 @@ API를 빌드하는 동안 일반적으로 특정 행동을 수행하기 위해
Pydantic 모델을 반환할 수도 있습니다(나중에 더 자세히 살펴봅니다).
JSON으로 자동 변환되는 객체들과 모델들이 많이 있습니다(ORM 등을 포함해서요). 가장 마음에 드는 것을 사용하세요, 이미 지원되고 있을 겁니다.
JSON으로 자동 변환되는 객체들과 모델들(ORM 등을 포함해서)이 많이 있습니다. 가장 마음에 드는 것을 사용하십시오, 이미 지원되고 있을 것입니다.
## 요약
* `FastAPI` 임포트.
* `app` 인스턴스 생성.
* (`@app.get("/")`처럼) **경로 동작 데코레이터** 작성.
* (위에 있는 `def root(): ...`처럼) **경로 동작 함수** 작성.
* (`@app.get("/")`처럼) **경로 작동 데코레이터** 작성.
* (위에 있는 `def root(): ...`처럼) **경로 작동 함수** 작성.
* (`uvicorn main:app --reload`처럼) 개발 서버 실행.

27
docs/ko/docs/tutorial/index.md
View File

@ -1,16 +1,16 @@
# 자습서 - 사용자 안내서
이 자습서는 **FastAPI**의 대부분의 기능을 단계별로 사용하는 방법을 보여줍니다.
이 자습서는 단계별로 **FastAPI**의 대부분의 기능에 대해 설명합니다.
각 섹션은 이전 섹션을 기반해서 점진적으로 만들어 졌지만, 주제에 따라 다르게 구성되었기 때문에 특정 API 요구사항을 해결하기 위해서라면 어느 특정 항목으로던지 직접 이동할 수 있습니다.
각 섹션은 이전 섹션에 기반하는 순차적인 구조로 작성되었지만, 각 주제로 구분되어 있기 때문에 필요에 따라 특정 섹션으로 바로 이동하여 필요한 내용을 바로 확인할 수 있습니다.
또한 향후 참조가 될 수 있도록 만들어졌습니다.
또한 향후에도 참조 자료로 쓰일 수 있도록 작성되었습니다.
그러므로 다시 돌아와서 정확히 필요한 것을 확인할 수 있습니다.
그러므로 필요할 때에 다시 돌아와서 원하는 것을 정확히 찾을 수 있습니다.
## 코드 실행하기
모든 코드 블록은 복사하고 직접 사용할 수 있습니다(실제로 테스트한 파이썬 파일입니다).
모든 코드 블록은 복사하여 바로 사용할 수 있습니다(실제로 테스트된 파이썬 파일입니다).
예제를 실행하려면 코드를 `main.py` 파일에 복사하고 다음을 사용하여 `uvicorn`을 시작합니다:
@ -28,17 +28,18 @@ $ uvicorn main:app --reload
</div>
코드를 작성하거나 복사, 편집할 때, 로컬에서 실행하는 것을 **강력히 장려**합니다.
코드를 작성하거나 복사, 편집할 때, 로컬 환경에서 실행하는 것을 **강력히 권장**합니다.
로컬 편집기에서 사용한다면, 모든 타입 검사와 자동완성 등 작성해야 하는 코드가 얼마나 적은지 보면서 FastAPI의 비로소 경험할 수 있습니다.
편집기에서 이렇게 사용한다면, 모든 타입 검사와 자동완성 등 작성해야 하는 코드가 얼마나 적은지 보면서 FastAPI의 장점을 실제로 확인할 수 있습니다.
---
## FastAPI 설치
첫 번째 단계는 FastAPI 설치입니다.
첫 번째 단계는 FastAPI를 설치하는 것입니다.
자습시에는 모든 선택적인 의존성 및 기능을 사용하여 설치할 수 있습니다:
자습시에는 모든 선택적인 의존성 및 기능을 함께 설치하는 것을 추천합니다:
<div class="termy">
@ -50,7 +51,7 @@ $ pip install "fastapi[all]"
</div>
...코드를 실행하는 서버로 사용할 수 있는 `uvicorn` 역시 포함하고 있습니다.
...이는 코드를 실행하는 서버로 사용할 수 있는 `uvicorn` 또한 포함하고 있습니다.
!!! note "참고"
부분적으로 설치할 수도 있습니다.
@ -73,8 +74,8 @@ $ pip install "fastapi[all]"
이 **자습서 - 사용자 안내서** 다음에 읽을 수 있는 **고급 사용자 안내서**도 있습니다.
**고급 사용자 안내서**는 현재 문서를 기반으로 하고, 동일한 개념을 사용하며, 추가 기능들을 알려줍니다.
**고급 사용자 안내서**는 현재 문서를 기반으로 하고, 동일한 개념을 사용하며, 추가적인 기능들에 대해 설명합니다.
하지만 (지금 읽고 있는) **자습서 - 사용자 안내서**를 먼저 읽는게 좋습니다.
하지만 (지금 읽고 있는) **자습서 - 사용자 안내서**를 먼저 읽는 것을 권장합니다.
**자습서 - 사용자 안내서**만으로도 완전한 애플리케이션을 구축할 수 있으며, 필요에 따라 **고급 사용자 안내서**에서 제공하는 몇 가지 추가적인 기능을 사용하여 다양한 방식으로 확장할 수 있도록 설계되었습니다.
**자습서 - 사용자 안내서**만으로도 완전한 애플리케이션을 구축할 수 있도록 작성되었으며, 필요에 따라 **고급 사용자 안내서**의 추가적인 아이디어를 적용하여 다양한 방식으로 확장할 수 있습니다.

74
docs/ko/docs/tutorial/path-params.md
View File

@ -1,6 +1,6 @@
# 경로 매개변수
파이썬 포맷 문자열이 사용하는 동일한 문법으로 "매개변수" 또는 "변수"를 경로에 선언할 수 있습니다:
파이썬의 포맷 문자열 리터럴에서 사용되는 문법을 이용하여 경로 "매개변수" 또는 "변수"를 선언할 수 있습니다:
```Python hl_lines="6-7"
{!../../../docs_src/path_params/tutorial001.py!}
@ -22,10 +22,10 @@
{!../../../docs_src/path_params/tutorial002.py!}
```
지금과 같은 경우, `item_id`는 `int`로 선언 되었습니다.
위의 예시에서, `item_id`는 `int`로 선언되었습니다.
!!! check "확인"
이 기능은 함수 내에서 오류 검사, 자동완성 등을 편집기를 지원합니다
이 기능은 함수 내에서 오류 검사, 자동완성 등의 편집기 기능을 활용할 수 있게 해줍니다.
## 데이터 <abbr title="다음으로도 알려져 있습니다: 직렬화, 파싱, 마샬링">변환</abbr>
@ -42,7 +42,7 @@
## 데이터 검증
하지만 브라우저에서 <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 오류를 볼 수 있습니다:
하지만 브라우저에서 <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
{
@ -61,12 +61,12 @@
경로 매개변수 `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>
`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와 상호 작용하는 코드를 개발하고 디버깅하는 데 매우 유용합니다.
@ -77,11 +77,11 @@
<img src="/img/tutorial/path-params/image01.png">
!!! check "확인"
다시 한번, 그저 파이썬 타입 선언을 하기만 하면 **FastAPI**는 자동 대화식 API 문서(Swagger UI 통합)를 제공합니다.
그저 파이썬 타입 선언을 하기만 하면 **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> 표준에서 나온 것이기 때문에 호환되는 도구가 많이 있습니다.
@ -89,53 +89,53 @@
<img src="/img/tutorial/path-params/image02.png">
이와 마찬가지로 호환되는 도구가 많이 있습니다. 다양한 언어에 대한 코드 생성 도구를 포함합니다.
이와 마찬가지로 다양한 언어에 대한 코드 생성 도구를 포함하여 여러 호환되는 도구가 있습니다.
## Pydantic
모든 데이터 검증은 <a href="https://pydantic-docs.helpmanual.io/" class="external-link" target="_blank">Pydantic</a>에 의해 내부적으로 수행되므로 이로 인한 모든 이점을 얻을 수 있습니다. 여러분은 관리를 잘 받고 있음을 느낄 수 있습니다.
모든 데이터 검증은 <a href="https://pydantic-docs.helpmanual.io/" class="external-link" target="_blank">Pydantic</a>에 의해 내부적으로 수행되므로 이로 인한 이점을 모두 얻을 수 있습니다. 여러분은 관리를 잘 받고 있음을 느낄 수 있습니다.
`str`, `float`, `bool`과 다른 복잡한 데이터 타입 선언을 할 수 있습니다.
`str`, `float`, `bool`, 그리고 다른 여러 복잡한 데이터 타입 선언을 할 수 있습니다.
이 중 몇 가지는 자습서의 다음 장에서 살펴봅니다.
이 중 몇 가지는 자습서의 다음 장에 설명되어 있습니다.
## 순서 문제
*경로 동작*을 만들때 고정 경로를 갖고 있는 상황들을 맞닥뜨릴 수 있습니다.
*경로 작동*을 만들때 고정 경로를 갖고 있는 상황들을 맞닥뜨릴 수 있습니다.
`/users/me`처럼, 현재 사용자의 데이터를 가져온다고 합시다.
사용자 ID를 이용해 특정 사용자의 정보를 가져오는 경로 `/users/{user_id}`도 있습니다.
*경로 동작*은 순차적으로 평가되기 때문에 `/users/{user_id}` 이전에 `/users/me`를 먼저 선언해야 합니다:
*경로 작동*은 순차적으로 실행되기 때문에 `/users/{user_id}` 이전에 `/users/me`를 먼저 선언해야 합니다:
```Python hl_lines="6 11"
{!../../../docs_src/path_params/tutorial003.py!}
```
그렇지 않으면 `/users/{user_id}`는 매개변수 `user_id`의 값을 `"me"`라고 "생각하여" `/users/me`도 연결합니다.
그렇지 않으면 `/users/{user_id}`는 `/users/me` 요청 또한 매개변수 `user_id`의 값이 `"me"`인 것으로 "생각하게" 됩니다.
## 사전정의 값
만약 *경로 매개변수*를 받는 *경로 동작*이 있지만, 유효하고 미리 정의할 수 있는 *경로 매개변수* 값을 원한다면 파이썬 표준 <abbr title="열거형(Enumeration)">`Enum`</abbr>을 사용할 수 있습니다.
만약 *경로 매개변수*를 받는 *경로 작동*이 있지만, *경로 매개변수*로 가능한 값들을 미리 정의하고 싶다면 파이썬 표준 <abbr title="열거형(Enumeration)">`Enum`</abbr>을 사용할 수 있습니다.
### `Enum` 클래스 생성
`Enum`을 임포트하고 `str`과 `Enum`을 상속하는 서브 클래스를 만듭니다.
`str`을 상속함으로써 API 문서는 값이 `string` 형이어야 하는 것을 알게 되고 제대로 렌더링 할 수 있게 됩니다.
`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 이후로 사용가능합니다.
<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>들의 이름입니다.
혹시 궁금하다면, "AlexNet", "ResNet", 그리고 "LeNet"은 그저 기계 학습 <abbr title="기술적으로 정확히는 딥 러닝 모델 구조">모델</abbr>들의 이름입니다.
### *경로 매개변수* 선언
@ -147,7 +147,7 @@
### 문서 확인
*경로 매개변수*에 사용할 수 있는 값은 미리 정의되어 있으므로 대화형 문서에서 멋지게 표시됩니다:
*경로 매개변수*에 사용할 수 있는 값은 미리 정의되어 있으므로 대화형 문서에서 잘 표시됩니다:
<img src="/img/tutorial/path-params/image03.png">
@ -157,7 +157,7 @@
#### *열거형 멤버* 비교
열거체 `ModelName`의 *열거형 멤버*를 비교할 수 있습니다:
열거형 `ModelName`의 *열거형 멤버*를 비교할 수 있습니다:
```Python hl_lines="17"
{!../../../docs_src/path_params/tutorial005.py!}
@ -165,7 +165,7 @@
#### *열거형 값* 가져오기
`model_name.value` 또는 일반적으로 `your_enum_member.value`를 이용하여 실제값(지금의 경우 `str`)을 가져올 수 있습니다:
`model_name.value` 또는 일반적으로 `your_enum_member.value`를 이용하여 실제 값(위 예시의 경우 `str`)을 가져올 수 있습니다:
```Python hl_lines="20"
{!../../../docs_src/path_params/tutorial005.py!}
@ -176,7 +176,7 @@
#### *열거형 멤버* 반환
*경로 동작*에서 중첩 JSON 본문(예: `dict`) 역시 *열거형 멤버*를 반환할 수 있습니다.
*경로 작동*에서 *열거형 멤버*를 반환할 수 있습니다. 이는 중첩 JSON 본문(예: `dict`)내의 값으로도 가능합니다.
클라이언트에 반환하기 전에 해당 값(이 경우 문자열)으로 변환됩니다:
@ -195,50 +195,50 @@
## 경로를 포함하는 경로 매개변수
`/files/{file_path}`가 있는 *경로 동작*이 있다고 해봅시다.
경로를 포함하는 *경로 작동* `/files/{file_path}`이 있다고 해봅시다.
그런데 여러분은 `home/johndoe/myfile.txt`처럼 *path*에 들어있는 `file_path` 자체가 필요합니다.
그런데 이 경우 `file_path` 자체가 `home/johndoe/myfile.txt`와 같은 경로를 포함해야 합니다.
따라서 해당 파일의 URL은 다음처럼 됩니다: `/files/home/johndoe/myfile.txt`.
이때 해당 파일의 URL은 다음처럼 됩니다: `/files/home/johndoe/myfile.txt`.
### OpenAPI 지원
테스트와 정의가 어려운 시나리오로 이어질 수 있으므로 OpenAPI는 *경로*를 포함하는 *경로 매개변수*를 내부에 선언하는 방법을 지원하지 않습니다.
그럼에도 Starlette의 내부 도구중 하나를 사용하여 **FastAPI**에서는 할 수 있습니다.
그럼에도 Starlette의 내부 도구중 하나를 사용하여 **FastAPI**에서는 이가 가능합니다.
매개변수에 경로가 포함되어야 한다는 문서를 추가하지 않아도 문서는 계속 작동합니다.
문서에 매개변수에 경로가 포함되어야 한다는 정보가 명시되지는 않지만 여전히 작동합니다.
### 경로 변환기
Starlette에서 직접 옵션을 사용하면 다음과 같은 URL을 사용하여 *path*를 포함하는 *경로 매개변수*를 선언 할 수 있습니다:
Starlette의 옵션을 직접 이용하여 다음과 같은 URL을 사용함으로써 *path*를 포함하는 *경로 매개변수*를 선언할 수 있습니다:
```
/files/{file_path:path}
```
이러한 경우 매개변수의 이름은 `file_path`이고 마지막 부분 `:path`는 매개변수가 *경로*와 일치해야함을 알려줍니다.
이러한 경우 매개변수의 이름은 `file_path`이며, 마지막 부분 `:path`는 매개변수가 *경로*와 일치해야 함을 명시합니다.
그러므로 다음과 같이 사용할 수 있습니다:
따라서 다음과 같이 사용할 수 있습니다:
```Python hl_lines="6"
{!../../../docs_src/path_params/tutorial004.py!}
```
!!! tip "팁"
매개변수가 `/home/johndoe/myfile.txt`를 갖고 있어 슬래시로 시작(`/`)해야 할 수 있습니다.
매개변수가 가져야 하는 값이 `/home/johndoe/myfile.txt`와 같이 슬래시로 시작(`/`)해야 할 수 있습니다.
이 경우 URL은: `/files//home/johndoe/myfile.txt`이며 `files`과 `home` 사이에 이중 슬래시(`//`)가 생깁니다.
## 요약
**FastAPI**과 함께라면 짧고 직관적인 표준 파이썬 타입 선언을 사용하여 다음을 얻을 수 있습니다:
**FastAPI**를 이용하면 짧고 직관적인 표준 파이썬 타입 선언을 사용하여 다음을 얻을 수 있습니다:
* 편집기 지원: 오류 검사, 자동완성 등
* 데이터 "<abbr title="HTTP 요청에서 전달되는 문자열을 파이썬 데이터로 변환">파싱</abbr>"
* 데이터 검증
* API 주석(Annotation)과 자동 문서
위 사항들을 그저 한번에 선언하면 됩니다.
단 한번의 선언만으로 위 사항들을 모두 선언할 수 있습니다.
이는 (원래 성능과는 별개로) 대체 프레임워크와 비교했을 때 **FastAPI**의 주요 가시적 장점일 것입니다.
이는 대체 프레임워크와 비교했을 때 (엄청나게 빠른 성능 외에도) **FastAPI**의 주요한 장점일 것입니다.

16
docs/ko/docs/tutorial/query-params.md
View File

@ -1,6 +1,6 @@
# 쿼리 매개변수
경로 매개변수의 일부가 아닌 다른 함수 매개변수를 선언할 때, "쿼리" 매개변수로 자동 해석합니다.
경로 매개변수의 일부가 아닌 다른 함수 매개변수를 선언하면 "쿼리" 매개변수로 자동 해석합니다.
```Python hl_lines="9"
{!../../../docs_src/query_params/tutorial001.py!}
@ -8,7 +8,7 @@
쿼리는 URL에서 `?` 후에 나오고 `&`으로 구분되는 키-값 쌍의 집합입니다.
예를 들어, URL에서:
예를 들어, 아래 URL에서:
```
http://127.0.0.1:8000/items/?skip=0&limit=10
@ -21,7 +21,7 @@ http://127.0.0.1:8000/items/?skip=0&limit=10
URL의 일부이므로 "자연스럽게" 문자열입니다.
하지만 파이썬 타입과 함께 선언할 경우(위 예에서 `int`), 해당 타입으로 변환되고 이에 대해 검증합니다.
하지만 파이썬 타입과 함께 선언할 경우(위 예에서 `int`), 해당 타입으로 변환 및 검증됩니다.
경로 매개변수에 적용된 동일한 프로세스가 쿼리 매개변수에도 적용됩니다:
@ -36,13 +36,13 @@ URL의 일부이므로 "자연스럽게" 문자열입니다.
위 예에서 `skip=0`과 `limit=10`은 기본값을 갖고 있습니다.
그러므로 URL로 이동하면:
그러므로 URL로 이동하는 것은:
```
http://127.0.0.1:8000/items/
```
아래로 이동한 것과 같습니다:
아래로 이동하는 것과 같습니다:
```
http://127.0.0.1:8000/items/?skip=0&limit=10
@ -136,7 +136,7 @@ http://127.0.0.1:8000/items/foo?short=yes
특정값을 추가하지 않고 선택적으로 만들기 위해선 기본값을 `None`으로 설정하면 됩니다.
그러나 쿼리 매개변수를 필수로 만들려면 기본값을 선언할 수 없습니다:
그러나 쿼리 매개변수를 필수로 만들려면 단순히 기본값을 선언하지 않으면 됩니다:
```Python hl_lines="6-7"
{!../../../docs_src/query_params/tutorial005.py!}
@ -144,7 +144,7 @@ http://127.0.0.1:8000/items/foo?short=yes
여기 쿼리 매개변수 `needy`는 `str`형인 필수 쿼리 매개변수입니다.
브라우저에서 URL을 아래처럼 연다면:
브라우저에서 아래와 같은 URL을 연다면:
```
http://127.0.0.1:8000/items/foo-item
@ -188,7 +188,7 @@ http://127.0.0.1:8000/items/foo-item?needy=sooooneedy
{!../../../docs_src/query_params/tutorial006.py!}
```
이 경우 3가지 쿼리 매개변수가 있습니다:
위 예시에서는 3가지 쿼리 매개변수가 있습니다:
* `needy`, 필수적인 `str`.
* `skip`, 기본값이 `0`인 `int`.