///

You can extend the OpenAPI schema for a *path operation* using the parameter `openapi_extra`.

### OpenAPI Extensions { #openapi-extensions }

This `openapi_extra` can be helpful, for example, to declare [OpenAPI Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specificationExtensions):

/// danger

Never store user's plaintext passwords. Always store a "secure hash" that you can then verify.

If you don't know, you will learn what a "password hash" is in the [security chapters](security/simple-oauth2.md#password-hashing).

///

## Multiple models { #multiple-models }

Here's a general idea of how the models could look like with their password fields and the places where they are used:

    * `Path()`
    * `Query()`
    * `Header()`
    * `Cookie()`
* [`Request Body Object`, in the field `content`, on the `Media Type Object` (in the specification)](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#media-type-object) that was used by FastAPI's:
    * `Body()`
    * `File()`

你也可以为它声明带有各自模型、状态码等的附加响应。

文档中有一个完整章节，你可以阅读这里的[OpenAPI 中的附加响应](additional-responses.md)。

## OpenAPI Extra { #openapi-extra }

当你在应用中声明一个 *路径操作* 时，**FastAPI** 会自动生成与该 *路径操作* 相关的元数据，以包含到 OpenAPI 方案中。

/// note | 技术细节

在 OpenAPI 规范中，这被称为 [Operation 对象](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#operation-object)。

///

它包含关于该 *路径操作* 的所有信息，并用于生成自动文档。

경로 매개변수가 정수형으로 선언된 것을 확인할 수 있습니다.

///

## 표준 기반의 이점, 대체 문서 { #standards-based-benefits-alternative-documentation }

그리고 생성된 스키마는 [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md) 표준에서 나온 것이기 때문에 호환되는 도구가 많이 있습니다.

이 덕분에 **FastAPI** 자체에서 [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc)로 접속할 수 있는 (ReDoc을 사용하는) 대체 API 문서를 제공합니다:

<img src="/img/tutorial/path-params/image02.png">

延續前一個範例，通常會有不只一個彼此相關的模型。

對使用者模型尤其如此，因為：

* 「輸入模型」需要能包含密碼。
* 「輸出模型」不應包含密碼。
* 「資料庫模型」通常需要儲存雜湊後的密碼。

/// danger

切勿儲存使用者的明文密碼。務必只儲存可供驗證的「安全雜湊」。

若你還不清楚，稍後會在[安全性章節](security/simple-oauth2.md#password-hashing)學到什麼是「密碼雜湊」。

///

## 多個模型 { #multiple-models }

以下是模型大致長相、與其密碼欄位以及它們被使用的位置：

{* ../../docs_src/extra_models/tutorial001_py310.py hl[7,9,14,20,22,27:28,31:33,38:39] *}

這會定義該*路徑操作*主要回應的中繼資料。

你也可以宣告額外的回應及其模型、狀態碼等。

文件中有完整章節說明，請見 [OpenAPI 中的額外回應](additional-responses.md)。

## OpenAPI 額外資訊 { #openapi-extra }

當你在應用程式中宣告一個*路徑操作*時，FastAPI 會自動產生該*路徑操作*的相關中繼資料，並納入 OpenAPI 結構中。

/// note | 技術細節

在 OpenAPI 規格中，這稱為 [Operation 物件](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#operation-object)。

///

它包含關於*路徑操作*的所有資訊，並用於產生自動文件。

- [`Parameter Object`（规范中）](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameter-object)，被 FastAPI 的以下内容使用：
    - `Path()`
    - `Query()`
    - `Header()`
    - `Cookie()`
- [`Request Body Object` 中的 `content` 字段里的 `Media Type Object`（规范中）](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#media-type-object)，被 FastAPI 的以下内容使用：
    - `Body()`
    - `File()`
    - `Form()`

* [`Parameter Object`（規範）](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameter-object)，對應到 FastAPI 的：
    * `Path()`
    * `Query()`
    * `Header()`
    * `Cookie()`
* [`Request Body Object` 中的 `content` 欄位裡的 `Media Type Object`（規範）](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#media-type-object)，對應到 FastAPI 的：
    * `Body()`
    * `File()`
    * `Form()`

/// info

これについてはドキュメントに章全体があります。 [OpenAPIの追加レスポンス](additional-responses.md) で読めます。

## OpenAPI Extra { #openapi-extra }

アプリケーションで *path operation* を宣言すると、**FastAPI** はOpenAPIスキーマに含めるために、その *path operation* に関連するメタデータを自動的に生成します。

/// note | 技術詳細

OpenAPI仕様では [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#operation-object) と呼ばれています。

///