diff --git a/docs/zh/docs/reference/apirouter.md b/docs/zh/docs/reference/apirouter.md new file mode 100644 index 000000000..15960cde4 --- /dev/null +++ b/docs/zh/docs/reference/apirouter.md @@ -0,0 +1,24 @@ +# `APIRouter` 类 + +下面是 `APIRouter` 类的参考信息，包括其所有参数、属性和方法。 + +你可以直接从 `fastapi` 中导入 `APIRouter` 类： + +```python +from fastapi import APIRouter +``` + +::: fastapi.APIRouter + options: + members: + - websocket + - include_router + - get + - put + - post + - delete + - options + - head + - patch + - trace + - on_event diff --git a/docs/zh/docs/reference/background.md b/docs/zh/docs/reference/background.md new file mode 100644 index 000000000..72761bc4e --- /dev/null +++ b/docs/zh/docs/reference/background.md @@ -0,0 +1,11 @@ +# 后台任务 - `BackgroundTasks` + +您可以在 *路径操作函数* 或依赖函数中声明一个类型为`BackgroundTasks`的参数，然后在发送响应后使用它来安排后台任务的执行。 + +您可以直接从 `fastapi` 中导入该参数： + +```python +from fastapi import BackgroundTasks +``` + +::: fastapi.BackgroundTasks diff --git a/docs/zh/docs/reference/dependencies.md b/docs/zh/docs/reference/dependencies.md new file mode 100644 index 000000000..5b93de28b --- /dev/null +++ b/docs/zh/docs/reference/dependencies.md @@ -0,0 +1,29 @@ +# 依赖项 - `Depends()` 和 `Security()` + +## `Depends()` + +依赖关系主要通过特殊函数 `Depends()` 来处理。 + +下面是该函数及其参数的引用。 + +您可以直接从 `fastapi` 中导入该参数： + +```python +from fastapi import Depends +``` + +::: fastapi.Depends + +## `Security()` + +在许多情况下，您可以使用 `Depends()`，通过依赖关系来处理安全性（授权、身份验证等）。 + +但如果您也想声明 OAuth2 作用域，则可以使用 `Security()`，而不是 `Depends()`。 + +你可以直接从 `fastapi` 导入 `Security()`： + +```python +from fastapi import Security +``` + +::: fastapi.Security diff --git a/docs/zh/docs/reference/encoders.md b/docs/zh/docs/reference/encoders.md new file mode 100644 index 000000000..a3760094a --- /dev/null +++ b/docs/zh/docs/reference/encoders.md @@ -0,0 +1,3 @@ +# 编码器 - `jsonable_encoder` + +::: fastapi.encoders.jsonable_encoder diff --git a/docs/zh/docs/reference/exceptions.md b/docs/zh/docs/reference/exceptions.md new file mode 100644 index 000000000..767fa04c8 --- /dev/null +++ b/docs/zh/docs/reference/exceptions.md @@ -0,0 +1,20 @@ +# 异常处理 - `HTTPException` and `WebSocketException` + +这些异常可以用来向客户端显示错误。 + +当您引发异常时，就像在普通 Python 中一样，其余的执行将被中止。这样，您就可以在代码的任何地方引发这些异常，以终止请求并向客户端显示错误。 + +您可以使用： + +* `HTTPException` +* `WebSocketException` + +可以直接从 `fastapi` 中导入这些异常： + +```python +from fastapi import HTTPException, WebSocketException +``` + +::: fastapi.HTTPException + +::: fastapi.WebSocketException diff --git a/docs/zh/docs/reference/fastapi.md b/docs/zh/docs/reference/fastapi.md new file mode 100644 index 000000000..331dd8eba --- /dev/null +++ b/docs/zh/docs/reference/fastapi.md @@ -0,0 +1,31 @@ +# `FastAPI` 类 + +下面是 `FastAPI` 类的参考信息，包括其所有参数、属性和方法。 + +你可以直接从 `fastapi` 中导入 `FastAPI` 类： + +```python +from fastapi import FastAPI +``` + +::: fastapi.FastAPI + options: + members: + - openapi_version + - webhooks + - state + - dependency_overrides + - openapi + - websocket + - include_router + - get + - put + - post + - delete + - options + - head + - patch + - trace + - on_event + - middleware + - exception_handler diff --git a/docs/zh/docs/reference/httpconnection.md b/docs/zh/docs/reference/httpconnection.md new file mode 100644 index 000000000..673d15e92 --- /dev/null +++ b/docs/zh/docs/reference/httpconnection.md @@ -0,0 +1,11 @@ +# `HTTPConnection` 类 + +当你想定义同时兼容 HTTP 和 WebSockets 的依赖关系时，你可以定义一个使用 `HTTPConnection` 而不是 `Request` 或 `WebSocket` 的参数。 + +您可以从 `fastapi.requests` 中导入该参数： + +```python +from fastapi.requests import HTTPConnection +``` + +::: fastapi.requests.HTTPConnection diff --git a/docs/zh/docs/reference/index.md b/docs/zh/docs/reference/index.md new file mode 100644 index 000000000..7cd3fcde6 --- /dev/null +++ b/docs/zh/docs/reference/index.md @@ -0,0 +1,6 @@ +# API参考 + +这里有代码 API、类、函数、参数、属性和您可以在应用程序中使用的所有 FastAPI 部件的参考说明。 + +如果您想**学习FastAPI**，最好阅读 +[FastAPI Tutorial](https://fastapi.tiangolo.com/zh/tutorial/). diff --git a/docs/zh/docs/reference/middleware.md b/docs/zh/docs/reference/middleware.md new file mode 100644 index 000000000..f6350be81 --- /dev/null +++ b/docs/zh/docs/reference/middleware.md @@ -0,0 +1,45 @@ +# 中间件 + +Starlette 可直接提供多个中间件。 + +请参阅 [FastAPI docs for Middleware](https://fastapi.tiangolo.com/zh/advanced/middleware/). + +::: fastapi.middleware.cors.CORSMiddleware + +可以这样从 `fastapi` 中导入它： + +```python +from fastapi.middleware.cors import CORSMiddleware +``` + +::: fastapi.middleware.gzip.GZipMiddleware + +可以这样从 `fastapi` 中导入它： + +```python +from fastapi.middleware.gzip import GZipMiddleware +``` + +::: fastapi.middleware.httpsredirect.HTTPSRedirectMiddleware + +可以这样从 `fastapi` 中导入它： + +```python +from fastapi.middleware.httpsredirect import HTTPSRedirectMiddleware +``` + +::: fastapi.middleware.trustedhost.TrustedHostMiddleware + +可以这样从 `fastapi` 中导入它： + +```python +from fastapi.middleware.trustedhost import TrustedHostMiddleware +``` + +::: fastapi.middleware.wsgi.WSGIMiddleware + +可以这样从 `fastapi` 中导入它： + +```python +from fastapi.middleware.wsgi import WSGIMiddleware +``` diff --git a/docs/zh/docs/reference/openapi/docs.md b/docs/zh/docs/reference/openapi/docs.md new file mode 100644 index 000000000..8a4b002ab --- /dev/null +++ b/docs/zh/docs/reference/openapi/docs.md @@ -0,0 +1,11 @@ +# OpenAPI `文档` + +用于处理 OpenAPI 自动用户界面文档的实用程序，包括 Swagger UI（默认位于 `/docs`）和 ReDoc（默认位于 `/redoc`）。 + +::: fastapi.openapi.docs.get_swagger_ui_html + +::: fastapi.openapi.docs.get_redoc_html + +::: fastapi.openapi.docs.get_swagger_ui_oauth2_redirect_html + +::: fastapi.openapi.docs.swagger_ui_default_parameters diff --git a/docs/zh/docs/reference/openapi/index.md b/docs/zh/docs/reference/openapi/index.md new file mode 100644 index 000000000..50959c8d4 --- /dev/null +++ b/docs/zh/docs/reference/openapi/index.md @@ -0,0 +1,5 @@ +# OpenAPI + +有几种实用程序可以处理 OpenAPI。 + +通常情况下，您不需要使用它们，除非您有特定的高级用例需要使用。 diff --git a/docs/zh/docs/reference/openapi/models.md b/docs/zh/docs/reference/openapi/models.md new file mode 100644 index 000000000..c966e38db --- /dev/null +++ b/docs/zh/docs/reference/openapi/models.md @@ -0,0 +1,5 @@ +# OpenAPI `模型` + +用于生成和验证生成的 OpenAPI 的 Pydantic 模型。 + +::: fastapi.openapi.models diff --git a/docs/zh/docs/reference/parameters.md b/docs/zh/docs/reference/parameters.md new file mode 100644 index 000000000..5ed2704b6 --- /dev/null +++ b/docs/zh/docs/reference/parameters.md @@ -0,0 +1,35 @@ +# 请求参数 + +这里是请求参数的参考信息。 + +这些是特殊函数，你可以把它们放在 *path 操作函数 * 参数或带有`注释`的依赖函数中，以便从请求中获取数据。 + +其中包括： + +* `Query()` +* `Path()` +* `Body()` +* `Cookie()` +* `Header()` +* `Form()` +* `File()` + +您可以直接从 `fastapi` 中导入它们： + +```python +from fastapi import Body, Cookie, File, Form, Header, Path, Query +``` + +::: fastapi.Query + +::: fastapi.Path + +::: fastapi.Body + +::: fastapi.Cookie + +::: fastapi.Header + +::: fastapi.Form + +::: fastapi.File diff --git a/docs/zh/docs/reference/request.md b/docs/zh/docs/reference/request.md new file mode 100644 index 000000000..8fe81cdf4 --- /dev/null +++ b/docs/zh/docs/reference/request.md @@ -0,0 +1,14 @@ +# `Request` 类 + +您可以将*路径操作函数*或依赖关系中的参数声明为 `Request`类型，这样就可以直接访问原始请求对象，而无需任何操作，例如验证。 + +你可以直接从 `fastapi` 导入： + +```python +from fastapi import Request +``` + +!!! tip + 如果要定义同时与 HTTP 和 WebSockets 兼容的依赖关系，可以定义一个使用 "HTTPConnection "而不是 "Request "或 "WebSocket "的参数。 + +::: fastapi.Request diff --git a/docs/zh/docs/reference/response.md b/docs/zh/docs/reference/response.md new file mode 100644 index 000000000..4c35206af --- /dev/null +++ b/docs/zh/docs/reference/response.md @@ -0,0 +1,13 @@ +# `Response` 类 + +您可以将*路径操作函数*或依赖关系中的参数声明为 `Response` 类型，然后为响应设置数据，如标题或 cookie。 + +您还可以直接使用它来创建一个实例，并从 *路径操作* 中返回。 + +您可以直接从 `fastapi` 中导入它： + +```python +from fastapi import Response +``` + +::: fastapi.Response diff --git a/docs/zh/docs/reference/responses.md b/docs/zh/docs/reference/responses.md new file mode 100644 index 000000000..7f406a4d3 --- /dev/null +++ b/docs/zh/docs/reference/responses.md @@ -0,0 +1,164 @@ +# 自定义响应 - 文件、HTML、重定向、流等 + +您可以使用多个自定义响应类来创建实例，并直接从 *path operations* 中返回。 + +请参阅 [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/zh/advanced/custom-response/). + +您可以直接从 `fastapi.responses` 导入: + +```python +from fastapi.responses import ( + FileResponse, + HTMLResponse, + JSONResponse, + ORJSONResponse, + PlainTextResponse, + RedirectResponse, + Response, + StreamingResponse, + UJSONResponse, +) +``` + +## FastAPI 响应 + +有几个自定义的 FastAPI 响应类，您可以使用它们来优化 JSON 性能。 + +::: fastapi.responses.UJSONResponse + options: + members: + - charset + - status_code + - media_type + - body + - background + - raw_headers + - render + - init_headers + - headers + - set_cookie + - delete_cookie + +::: fastapi.responses.ORJSONResponse + options: + members: + - charset + - status_code + - media_type + - body + - background + - raw_headers + - render + - init_headers + - headers + - set_cookie + - delete_cookie + +## Starlette 响应 + +::: fastapi.responses.FileResponse + options: + members: + - chunk_size + - charset + - status_code + - media_type + - body + - background + - raw_headers + - render + - init_headers + - headers + - set_cookie + - delete_cookie + +::: fastapi.responses.HTMLResponse + options: + members: + - charset + - status_code + - media_type + - body + - background + - raw_headers + - render + - init_headers + - headers + - set_cookie + - delete_cookie + +::: fastapi.responses.JSONResponse + options: + members: + - charset + - status_code + - media_type + - body + - background + - raw_headers + - render + - init_headers + - headers + - set_cookie + - delete_cookie + +::: fastapi.responses.PlainTextResponse + options: + members: + - charset + - status_code + - media_type + - body + - background + - raw_headers + - render + - init_headers + - headers + - set_cookie + - delete_cookie + +::: fastapi.responses.RedirectResponse + options: + members: + - charset + - status_code + - media_type + - body + - background + - raw_headers + - render + - init_headers + - headers + - set_cookie + - delete_cookie + +::: fastapi.responses.Response + options: + members: + - charset + - status_code + - media_type + - body + - background + - raw_headers + - render + - init_headers + - headers + - set_cookie + - delete_cookie + +::: fastapi.responses.StreamingResponse + options: + members: + - body_iterator + - charset + - status_code + - media_type + - body + - background + - raw_headers + - render + - init_headers + - headers + - set_cookie + - delete_cookie diff --git a/docs/zh/docs/reference/security/index.md b/docs/zh/docs/reference/security/index.md new file mode 100644 index 000000000..10fee988c --- /dev/null +++ b/docs/zh/docs/reference/security/index.md @@ -0,0 +1,73 @@ +# 安全工具 + +当您需要使用 OAuth2 作用域声明依赖关系时，可以使用 `Security()`。 + +但您仍然需要定义什么是依赖项，即作为参数传递给`Depends()`或`Security()`的可调用项。 + +您可以使用多种工具来创建这些依赖项，并将它们集成到 OpenAPI 中，这样它们就会显示在自动文档用户界面中，自动生成的客户端和 SDK 等也可以使用它们。 + +您可以从 `fastapi.security` 中导入它们： + +```python +from fastapi.security import ( + APIKeyCookie, + APIKeyHeader, + APIKeyQuery, + HTTPAuthorizationCredentials, + HTTPBasic, + HTTPBasicCredentials, + HTTPBearer, + HTTPDigest, + OAuth2, + OAuth2AuthorizationCodeBearer, + OAuth2PasswordBearer, + OAuth2PasswordRequestForm, + OAuth2PasswordRequestFormStrict, + OpenIdConnect, + SecurityScopes, +) +``` + +## API 密钥安全机制 + +::: fastapi.security.APIKeyCookie + +::: fastapi.security.APIKeyHeader + +::: fastapi.security.APIKeyQuery + +## HTTP 认证方案 + +::: fastapi.security.HTTPBasic + +::: fastapi.security.HTTPBearer + +::: fastapi.security.HTTPDigest + +## HTTP 凭据 + +::: fastapi.security.HTTPAuthorizationCredentials + +::: fastapi.security.HTTPBasicCredentials + +## OAuth 2.0 认证 + +::: fastapi.security.OAuth2 + +::: fastapi.security.OAuth2AuthorizationCodeBearer + +::: fastapi.security.OAuth2PasswordBearer + +## OAuth 2.0 密码表单模式 + +::: fastapi.security.OAuth2PasswordRequestForm + +::: fastapi.security.OAuth2PasswordRequestFormStrict + +## 依赖项中的 OAuth2 安全范围 + +::: fastapi.security.SecurityScopes + +## OpenID 连接 + +::: fastapi.security.OpenIdConnect diff --git a/docs/zh/docs/reference/staticfiles.md b/docs/zh/docs/reference/staticfiles.md new file mode 100644 index 000000000..d3bd684d4 --- /dev/null +++ b/docs/zh/docs/reference/staticfiles.md @@ -0,0 +1,13 @@ +# 静态文件 - `StaticFiles` + +您可以使用 `StaticFiles` 类提供 JavaScript、CSS、图片等静态文件。 + +请参阅 [FastAPI docs for Static Files](https://fastapi.tiangolo.com/zh/tutorial/static-files/). + +你可以直接从 `fastapi.staticfiles` 导入: + +```python +from fastapi.staticfiles import StaticFiles +``` + +::: fastapi.staticfiles.StaticFiles diff --git a/docs/zh/docs/reference/status.md b/docs/zh/docs/reference/status.md new file mode 100644 index 000000000..7bd49dda7 --- /dev/null +++ b/docs/zh/docs/reference/status.md @@ -0,0 +1,36 @@ +# 状态码 + +你可以直接从 `fastapi` 中导入 `status`: + +```python +from fastapi import status +``` + +`status` 由 Starlette 直接提供。 + +它包含一组带有整数状态代码的命名常量（变量）。 + +例如： + +* 200: `status.HTTP_200_OK` +* 403: `status.HTTP_403_FORBIDDEN` +* etc. + +在应用程序中使用名称自动完成功能快速访问 HTTP（和 WebSocket）状态代码非常方便，无需记忆整数状态代码。 + +请参阅 [FastAPI docs about Response Status Code](https://fastapi.tiangolo.com/zh/tutorial/response-status-code/). + +## 示例 + +```python +from fastapi import FastAPI, status + +app = FastAPI() + + +@app.get("/items/", status_code=status.HTTP_418_IM_A_TEAPOT) +def read_items(): + return [{"name": "Plumbus"}, {"name": "Portal Gun"}] +``` + +::: fastapi.status diff --git a/docs/zh/docs/reference/templating.md b/docs/zh/docs/reference/templating.md new file mode 100644 index 000000000..7cbb585a4 --- /dev/null +++ b/docs/zh/docs/reference/templating.md @@ -0,0 +1,13 @@ +# 模板 - `Jinja2Templates` 类 + +您可以使用 `Jinja2Templates` 类来呈现jinja2模板。 + +请参阅 [FastAPI docs for Templates](https://fastapi.tiangolo.com/zh/advanced/templates/)。 + +您可以直接从 `fastapi.templating` 中导入该类： + +```python +from fastapi.templating import Jinja2Templates +``` + +::: fastapi.templating.Jinja2Templates diff --git a/docs/zh/docs/reference/testclient.md b/docs/zh/docs/reference/testclient.md new file mode 100644 index 000000000..11fd2b71c --- /dev/null +++ b/docs/zh/docs/reference/testclient.md @@ -0,0 +1,13 @@ +# 测试客户端 - `TestClient` 类 + +您可以使用 `TestClient` 类测试 FastAPI 应用程序，而无需创建实际的 HTTP 和套接字连接，只需直接与 FastAPI 代码通信即可。 + +请参阅 [FastAPI docs for Testing](https://fastapi.tiangolo.com/zh/tutorial/testing/)，了解更多相关信息。 + +您可以直接从 `fastapi.testclient` 中导入该类： + +```python +from fastapi.testclient import TestClient +``` + +::: fastapi.testclient.TestClient diff --git a/docs/zh/docs/reference/uploadfile.md b/docs/zh/docs/reference/uploadfile.md new file mode 100644 index 000000000..9eccba7ca --- /dev/null +++ b/docs/zh/docs/reference/uploadfile.md @@ -0,0 +1,22 @@ +# `UploadFile` 类 + +您可以定义 *path operation function* 参数为 `UploadFile` 类型，以便从请求中接收文件。 + +你可以直接从 `fastapi` 中导入： + +```python +from fastapi import UploadFile +``` + +::: fastapi.UploadFile + options: + members: + - file + - filename + - size + - headers + - content_type + - read + - write + - seek + - close diff --git a/docs/zh/docs/reference/websockets.md b/docs/zh/docs/reference/websockets.md new file mode 100644 index 000000000..0478e6e9d --- /dev/null +++ b/docs/zh/docs/reference/websockets.md @@ -0,0 +1,66 @@ +# WebSockets + +在定义 WebSockets 时，通常要声明一个 `WebSocket` 类型的参数，通过它可以从客户端读取数据并向其发送数据。 + +它由 Starlette 直接提供，但也可以从 `fastapi` 中导入： + +```python +from fastapi import WebSocket +``` + +!!! tip + 如果要定义同时与 HTTP 和 WebSockets 兼容的依赖关系，可以定义一个使用 "HTTPConnection "而不是 "Request "或 "WebSocket "的参数。 + +::: fastapi.WebSocket + options: + members: + - scope + - app + - url + - base_url + - headers + - query_params + - path_params + - cookies + - client + - state + - url_for + - client_state + - application_state + - receive + - send + - accept + - receive_text + - receive_bytes + - receive_json + - iter_text + - iter_bytes + - iter_json + - send_text + - send_bytes + - send_json + - close + +当客户端断开连接时，会产生一个 `WebSocketDisconnect` 异常，你可以捕获它。 + +你可以直接从 `fastapi` 中导入： + +```python +from fastapi import WebSocketDisconnect +``` + +::: fastapi.WebSocketDisconnect + +### WebSockets - 附加类 + +用于处理 WebSockets 的附加类。 + +由 Starlette 直接提供，但也可以从 `fastapi` 中导入： + +```python +from fastapi.websockets import WebSocketDisconnect, WebSocketState +``` + +::: fastapi.websockets.WebSocketDisconnect + +::: fastapi.websockets.WebSocketState