### 加入自訂文件 { #include-the-custom-docs }

現在你可以為自訂文件建立「路徑操作（path operation）」。

你可以重用 FastAPI 的內部函式來建立文件的 HTML 頁面，並傳入所需參數：

* `openapi_url`：文件 HTML 頁面用來取得你 API 的 OpenAPI schema 的 URL。可使用屬性 `app.openapi_url`。
* `title`：你的 API 標題。
* `oauth2_redirect_url`：可使用 `app.swagger_ui_oauth2_redirect_url` 以沿用預設值。
* `swagger_js_url`：Swagger UI 文件 HTML 用來取得「JavaScript」檔案的 URL。這是你的自訂 CDN 位址。

例如，在 `Image` 模型中有一個 `url` 欄位，我們可以將其宣告為 Pydantic 的 `HttpUrl`，而不是 `str`：

{* ../../docs_src/body_nested_models/tutorial005_py310.py hl[2,8] *}

該字串會被檢查是否為有效的 URL，並在 JSON Schema / OpenAPI 中相應註記。

## 具有子模型列表的屬性 { #attributes-with-lists-of-submodels }

你也可以將 Pydantic 模型作為 `list`、`set` 等的子型別使用：

{* ../../docs_src/body_nested_models/tutorial006_py310.py hl[18] *}

    ["/optional-str", "/model-optional-str"],
)
def test_optional_str_schema(path: str):
    openapi = app.openapi()
    body_model_name = get_body_model_name(openapi, path)

    assert app.openapi()["components"]["schemas"][body_model_name] == {
        "properties": {
            "p": {
                "anyOf": [{"type": "string"}, {"type": "null"}],
                "title": "P",
            },
        },

OpenAPI propose une manière de définir plusieurs « schémas » de sécurité.

En les utilisant, vous pouvez tirer parti de tous ces outils basés sur des standards, y compris ces systèmes de documentation interactive.

OpenAPI définit les schémas de sécurité suivants :

* `apiKey` : une clé spécifique à l'application qui peut provenir :
    * D'un paramètre de requête.

///

## Integrated with OpenAPI { #integrated-with-openapi }

All the request declarations, validations and requirements of your dependencies (and sub-dependencies) will be integrated in the same OpenAPI schema.

So, the interactive docs will have all the information from these dependencies too:

<img src="/img/tutorial/dependencies/image01.png">

## Simple usage { #simple-usage }

すべて既存の代替手段を使うことで、そのすべてを学び、アイデアを得て、自分や一緒に仕事をしてきた開発者のチームにとって最良の方法で組み合わせる機会を得ました。

たとえば、理想的にはPythonの標準的な型ヒントに基づくべきであることが明らかになりました。

また、すでにある規格を利用するのがベストな方法でした。

そこで、**FastAPI**のコードを書き始める前に、OpenAPI、JSON Schema、OAuth2などの仕様を数ヶ月かけて勉強し、それらの関係、重複する箇所、相違点を理解しました。

## 設計 { #design }

その後、 (FastAPIを使う開発者として) ユーザーが欲しい「API」の設計に時間を費やしました。

もっとも人気のあるPythonエディターでいくつかのアイデアをテストしました。PyCharm、VS Code、Jediベースのエディターです。

    /**
     * Enumeration of model versions that can be validated.
     * These versions correspond to different levels of validation that can be applied
     * during model building, based on the POM schema version.
     * <p>
     * The validation levels are cumulative, with higher versions including all validations
     * from lower versions plus additional checks specific to that version.
     */
    enum Version {

To convert any data to JSON-compatible, read the docs for [Tutorial - JSON Compatible Encoder](../tutorial/encoder.md).

## OpenAPI Metadata - Docs { #openapi-metadata-docs }

To add metadata to your OpenAPI schema, including a license, version, contact, etc, read the docs for [Tutorial - Metadata and Docs URLs](../tutorial/metadata.md).

## OpenAPI Custom URL { #openapi-custom-url }

        * Nas respostas, o `set` será convertido para uma `list`.
        * O esquema gerado vai especificar que os valores do `set` são únicos (usando o `uniqueItems` do JSON Schema).
* `bytes`:
    * O `bytes` padrão do Python.
    * Em requisições e respostas será representado como uma `str`.
    * O esquema gerado vai especificar que é uma `str` com o "formato" `binary`.
* `Decimal`:

        "/optional-uploadfile",
    ],
)
def test_optional_schema(path: str):
    openapi = app.openapi()
    body_model_name = get_body_model_name(openapi, path)

    assert app.openapi()["components"]["schemas"][body_model_name] == {
        "properties": {
            "p": {
                "anyOf": [
                    {"type": "string", "contentMediaType": "application/octet-stream"},
                    {"type": "null"},