repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v6.0.0
    hooks:
      - id: check-added-large-files
        args: ['--maxkb=750']
        exclude: ^uv.lock$
      - id: check-toml
      - id: check-yaml
        args:
        - --unsafe
      - id: end-of-file-fixer
      - id: trailing-whitespace

  - repo: local
    hooks:
      - id: local-ruff-check
        name: ruff check

Slawomir Jaranowski <******@****.***> 1774793470 +0200

{* ../../docs_src/path_operation_advanced_configuration/tutorial007_py310.py hl[15:20, 22] *}

儘管沒有使用預設的內建功能，我們仍透過 Pydantic 模型手動產生想以 YAML 接收之資料的 JSON Schema。

接著我們直接使用請求，並將本文擷取為 `bytes`。這表示 FastAPI 甚至不會嘗試把請求負載解析為 JSON。

然後在程式中直接解析該 YAML 內容，並再次使用相同的 Pydantic 模型來驗證該 YAML 內容：

{* ../../docs_src/path_operation_advanced_configuration/tutorial007_py310.py hl[15:20, 22] *}

それでも、デフォルトの統合機能を使っていないにもかかわらず、YAMLで受け取りたいデータのために、Pydanticモデルを使って手動でJSON Schemaを生成しています。

そしてリクエストを直接使い、ボディを `bytes` として抽出します。これは、FastAPIがリクエストペイロードをJSONとしてパースしようとすらしないことを意味します。

その後、コード内でそのYAMLコンテンツを直接パースし、さらに同じPydanticモデルを使ってYAMLコンテンツを検証しています。

例如，在这个应用中我们不使用 FastAPI 集成的从 Pydantic 模型提取 JSON Schema 的功能，也不使用对 JSON 的自动校验。实际上，我们将请求的内容类型声明为 YAML，而不是 JSON：

{* ../../docs_src/path_operation_advanced_configuration/tutorial007_py310.py hl[15:20, 22] *}

尽管我们没有使用默认的集成功能，我们仍然使用 Pydantic 模型手动生成我们想以 YAML 接收的数据的 JSON Schema。

然后我们直接使用请求并将请求体提取为 `bytes`。这意味着 FastAPI 甚至不会尝试将请求负载解析为 JSON。

接着在我们的代码中，我们直接解析该 YAML 内容，然后再次使用同一个 Pydantic 模型来验证该 YAML 内容：

        OutputStream jsonOutput = SearchEngineUtil.getXContentBuilderOutputStream(callback, XContentType.JSON);
        assertNotNull(jsonOutput);

        // Test with YAML
        OutputStream yamlOutput = SearchEngineUtil.getXContentBuilderOutputStream(callback, XContentType.YAML);
        assertNotNull(yamlOutput);
    }

    @Test
    public void test_getXContentOutputStream_success() {
        ToXContent xContent = new ToXContent() {

{* ../../docs_src/path_operation_advanced_configuration/tutorial007_py310.py hl[15:20, 22] *}

그럼에도 기본 통합 기능을 사용하지 않더라도, YAML로 받고자 하는 데이터에 대한 JSON Schema를 수동으로 생성하기 위해 Pydantic 모델을 여전히 사용합니다.

그 다음 요청을 직접 사용하고, 바디를 `bytes`로 추출합니다. 이는 FastAPI가 요청 페이로드를 JSON으로 파싱하려고 시도조차 하지 않는다는 뜻입니다.

그리고 코드에서 YAML 콘텐츠를 직접 파싱한 뒤, 다시 같은 Pydantic 모델을 사용해 YAML 콘텐츠를 검증합니다:

但文档仍然缺失，于是出现了 APISpec。

它为许多框架提供插件（Starlette 也有插件）。

它的工作方式是：你在处理路由的每个函数的文档字符串里，用 YAML 格式编写模式定义。

然后它会生成 OpenAPI 模式。

这正是它在 Flask、Starlette、Responder 等框架里的工作方式。

但这样我们又回到了在 Python 字符串中维护一套“微语法”（一大段 YAML）的问题上。

编辑器很难为此提供帮助；而且如果我们修改了参数或 Marshmallow 模式，却忘了同步更新那个 YAML 文档字符串，生成的模式就会过时。

/// info | 信息

APISpec 由与 Marshmallow 相同的开发者创建。

///

但文件仍然缺失，於是 APISpec 出現了。

它是多個框架的外掛（Starlette 也有對應外掛）。

它的作法是：你在處理路由的每個函式的 docstring 中，用 YAML 格式撰寫結構定義。

然後它會產生 OpenAPI schemas。

在 Flask、Starlette、Responder 等框架中都是這樣運作。

但這又帶來一個問題：在 Python 字串中（大型 YAML）加入一段微語法。

編輯器幫不上太多忙。而且如果我們修改了參數或 Marshmallow 的 schemas 卻忘了同步修改 YAML docstring，產生的結構就會過時。

/// info

APISpec 由與 Marshmallow 相同的開發者創建。

///

/// check | 啟發 **FastAPI**

- Added machine readable output options (JSON & YAML) to kubectl api-resources ([#132604](https://github.com/kubernetes/kubernetes/pull/132604), [@dharmit](https://github.com/dharmit)) [SIG Apps, CLI and Network]