Skip to content

Commit 7226250

Browse files
github-actions[bot]github-actions[bot]
committed
🌐 Update translations for ko (add-missing)
1 parent effe493 commit 7226250

34 files changed

Lines changed: 5999 additions & 0 deletions

‎docs/ko/docs/_llm-test.md‎

Lines changed: 503 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/ko/docs/advanced/additional-responses.md‎

Lines changed: 247 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,247 @@
1+
# OpenAPI에서 추가 응답 { #additional-responses-in-openapi }
2+
3+
/// warning | 경고
4+
5+
이는 꽤 고급 주제입니다.
6+
7+
**FastAPI**를 막 시작했다면, 이 내용이 필요 없을 수도 있습니다.
8+
9+
///
10+
11+
추가 상태 코드, 미디어 타입, 설명 등을 포함한 추가 응답을 선언할 수 있습니다.
12+
13+
이러한 추가 응답은 OpenAPI 스키마에 포함되므로 API 문서에도 표시됩니다.
14+
15+
하지만 이러한 추가 응답의 경우, 상태 코드와 콘텐츠를 포함하여 `JSONResponse` 같은 `Response`를 직접 반환하도록 반드시 처리해야 합니다.
16+
17+
## `model`을 사용한 추가 응답 { #additional-response-with-model }
18+
19+
*경로 처리 데코레이터*에 `responses` 파라미터를 전달할 수 있습니다.
20+
21+
이는 `dict`를 받습니다. 키는 각 응답의 상태 코드(예: `200`)이고, 값은 각 응답에 대한 정보를 담은 다른 `dict`입니다.
22+
23+
각 응답 `dict`에는 `response_model`처럼 Pydantic 모델을 담는 `model` 키가 있을 수 있습니다.
24+
25+
**FastAPI**는 그 모델을 사용해 JSON Schema를 생성하고, OpenAPI의 올바른 위치에 포함합니다.
26+
27+
예를 들어, 상태 코드 `404`와 Pydantic 모델 `Message`를 사용하는 다른 응답을 선언하려면 다음과 같이 작성할 수 있습니다:
28+
29+
{* ../../docs_src/additional_responses/tutorial001_py39.py hl[18,22] *}
30+
31+
/// note | 참고
32+
33+
`JSONResponse`를 직접 반환해야 한다는 점을 기억하세요.
34+
35+
///
36+
37+
/// info | 정보
38+
39+
`model` 키는 OpenAPI의 일부가 아닙니다.
40+
41+
**FastAPI**는 여기에서 Pydantic 모델을 가져와 JSON Schema를 생성하고 올바른 위치에 넣습니다.
42+
43+
올바른 위치는 다음과 같습니다:
44+
45+
* 값으로 또 다른 JSON 객체(`dict`)를 가지는 `content` 키 안에:
46+
* 미디어 타입(예: `application/json`)을 키로 가지며, 값으로 또 다른 JSON 객체를 포함하고:
47+
* `schema` 키가 있고, 그 값이 모델에서 생성된 JSON Schema입니다. 이것이 올바른 위치입니다.
48+
* **FastAPI**는 이를 직접 포함하는 대신, OpenAPI의 다른 위치에 있는 전역 JSON Schemas를 참조하도록 여기에서 reference를 추가합니다. 이렇게 하면 다른 애플리케이션과 클라이언트가 그 JSON Schema를 직접 사용할 수 있고, 더 나은 코드 생성 도구 등을 제공할 수 있습니다.
49+
50+
///
51+
52+
이 *경로 처리*에 대해 OpenAPI에 생성되는 응답은 다음과 같습니다:
53+
54+
```JSON hl_lines="3-12"
55+
{
56+
"responses": {
57+
"404": {
58+
"description": "Additional Response",
59+
"content": {
60+
"application/json": {
61+
"schema": {
62+
"$ref": "#/components/schemas/Message"
63+
}
64+
}
65+
}
66+
},
67+
"200": {
68+
"description": "Successful Response",
69+
"content": {
70+
"application/json": {
71+
"schema": {
72+
"$ref": "#/components/schemas/Item"
73+
}
74+
}
75+
}
76+
},
77+
"422": {
78+
"description": "Validation Error",
79+
"content": {
80+
"application/json": {
81+
"schema": {
82+
"$ref": "#/components/schemas/HTTPValidationError"
83+
}
84+
}
85+
}
86+
}
87+
}
88+
}
89+
```
90+
91+
스키마는 OpenAPI 스키마 내부의 다른 위치를 참조합니다:
92+
93+
```JSON hl_lines="4-16"
94+
{
95+
"components": {
96+
"schemas": {
97+
"Message": {
98+
"title": "Message",
99+
"required": [
100+
"message"
101+
],
102+
"type": "object",
103+
"properties": {
104+
"message": {
105+
"title": "Message",
106+
"type": "string"
107+
}
108+
}
109+
},
110+
"Item": {
111+
"title": "Item",
112+
"required": [
113+
"id",
114+
"value"
115+
],
116+
"type": "object",
117+
"properties": {
118+
"id": {
119+
"title": "Id",
120+
"type": "string"
121+
},
122+
"value": {
123+
"title": "Value",
124+
"type": "string"
125+
}
126+
}
127+
},
128+
"ValidationError": {
129+
"title": "ValidationError",
130+
"required": [
131+
"loc",
132+
"msg",
133+
"type"
134+
],
135+
"type": "object",
136+
"properties": {
137+
"loc": {
138+
"title": "Location",
139+
"type": "array",
140+
"items": {
141+
"type": "string"
142+
}
143+
},
144+
"msg": {
145+
"title": "Message",
146+
"type": "string"
147+
},
148+
"type": {
149+
"title": "Error Type",
150+
"type": "string"
151+
}
152+
}
153+
},
154+
"HTTPValidationError": {
155+
"title": "HTTPValidationError",
156+
"type": "object",
157+
"properties": {
158+
"detail": {
159+
"title": "Detail",
160+
"type": "array",
161+
"items": {
162+
"$ref": "#/components/schemas/ValidationError"
163+
}
164+
}
165+
}
166+
}
167+
}
168+
}
169+
}
170+
```
171+
172+
## 주요 응답에 대한 추가 미디어 타입 { #additional-media-types-for-the-main-response }
173+
174+
같은 `responses` 파라미터를 사용해 동일한 주요 응답에 대해 다른 미디어 타입을 추가할 수도 있습니다.
175+
176+
예를 들어, *경로 처리*가 JSON 객체(미디어 타입 `application/json`) 또는 PNG 이미지(미디어 타입 `image/png`)를 반환할 수 있다고 선언하기 위해 `image/png`라는 추가 미디어 타입을 추가할 수 있습니다:
177+
178+
{* ../../docs_src/additional_responses/tutorial002_py310.py hl[17:22,26] *}
179+
180+
/// note | 참고
181+
182+
이미지는 `FileResponse`를 사용해 직접 반환해야 한다는 점에 유의하세요.
183+
184+
///
185+
186+
/// info | 정보
187+
188+
`responses` 파라미터에서 다른 미디어 타입을 명시적으로 지정하지 않는 한, FastAPI는 응답이 주요 응답 클래스와 동일한 미디어 타입(기본값 `application/json`)을 가진다고 가정합니다.
189+
190+
하지만 커스텀 응답 클래스를 지정하면서 미디어 타입을 `None`으로 설정했다면, FastAPI는 연결된 모델이 있는 모든 추가 응답에 대해 `application/json`을 사용합니다.
191+
192+
///
193+
194+
## 정보 결합하기 { #combining-information }
195+
196+
`response_model`, `status_code`, `responses` 파라미터를 포함해 여러 위치의 응답 정보를 결합할 수도 있습니다.
197+
198+
기본 상태 코드 `200`(또는 필요하다면 커스텀 코드)을 사용하여 `response_model`을 선언하고, 그와 동일한 응답에 대한 추가 정보를 `responses`에서 OpenAPI 스키마에 직접 선언할 수 있습니다.
199+
200+
**FastAPI**는 `responses`의 추가 정보를 유지하고, 모델의 JSON Schema와 결합합니다.
201+
202+
예를 들어, Pydantic 모델을 사용하고 커스텀 `description`을 가진 상태 코드 `404` 응답을 선언할 수 있습니다.
203+
204+
또한 `response_model`을 사용하는 상태 코드 `200` 응답을 선언하되, 커스텀 `example`을 포함할 수도 있습니다:
205+
206+
{* ../../docs_src/additional_responses/tutorial003_py39.py hl[20:31] *}
207+
208+
이 모든 내용은 OpenAPI에 결합되어 포함되고, API 문서에 표시됩니다:
209+
210+
<img src="/img/tutorial/additional-responses/image01.png">
211+
212+
## 미리 정의된 응답과 커스텀 응답 결합하기 { #combine-predefined-responses-and-custom-ones }
213+
214+
여러 *경로 처리*에 적용되는 미리 정의된 응답이 필요할 수도 있지만, 각 *경로 처리*마다 필요한 커스텀 응답과 결합하고 싶을 수도 있습니다.
215+
216+
그런 경우 Python의 `dict` “unpacking” 기법인 `**dict_to_unpack`을 사용할 수 있습니다:
217+
218+
```Python
219+
old_dict = {
220+
"old key": "old value",
221+
"second old key": "second old value",
222+
}
223+
new_dict = {**old_dict, "new key": "new value"}
224+
```
225+
226+
여기서 `new_dict`는 `old_dict`의 모든 키-값 쌍에 더해 새 키-값 쌍까지 포함합니다:
227+
228+
```Python
229+
{
230+
"old key": "old value",
231+
"second old key": "second old value",
232+
"new key": "new value",
233+
}
234+
```
235+
236+
이 기법을 사용해 *경로 처리*에서 일부 미리 정의된 응답을 재사용하고, 추가 커스텀 응답과 결합할 수 있습니다.
237+
238+
예를 들어:
239+
240+
{* ../../docs_src/additional_responses/tutorial004_py310.py hl[11:15,24] *}
241+
242+
## OpenAPI 응답에 대한 추가 정보 { #more-information-about-openapi-responses }
243+
244+
응답에 정확히 무엇을 포함할 수 있는지 보려면, OpenAPI 사양의 다음 섹션을 확인하세요:
245+
246+
* <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#responses-object" class="external-link" target="_blank">OpenAPI Responses Object</a>: `Response Object`를 포함합니다.
247+
* <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#response-object" class="external-link" target="_blank">OpenAPI Response Object</a>: `responses` 파라미터 안의 각 응답에 이것의 어떤 항목이든 직접 포함할 수 있습니다. `description`, `headers`, `content`(여기에서 서로 다른 미디어 타입과 JSON Schema를 선언합니다), `links` 등을 포함할 수 있습니다.

0 commit comments

Comments
 (0)