## Webhooks mit **FastAPI** und OpenAPI dokumentieren { #documenting-webhooks-with-fastapi-and-openapi }

Mit **FastAPI**, mithilfe von OpenAPI, können Sie die Namen dieser Webhooks, die Arten von HTTP-Operationen, die Ihre App senden kann (z. B. `POST`, `PUT`, usw.) und die **Requestbodys** definieren, die Ihre App senden würde.

在 FastAPI 中，透過 OpenAPI，你可以定義這些 webhook 的名稱、你的應用將發送的 HTTP 操作類型（例如 `POST`、`PUT` 等），以及你的應用要發送的請求主體。

這能讓你的使用者更容易實作他們的 API 以接收你的 webhook 請求，甚至可能自動產生部分他們自己的 API 程式碼。

/// info

Webhook 功能自 OpenAPI 3.1.0 起提供，FastAPI `0.99.0` 以上版本支援。

///

## 含有 webhook 的應用 { #an-app-with-webhooks }

# Расширение OpenAPI { #extending-openapi }

Иногда может понадобиться изменить сгенерированную схему OpenAPI.

В этом разделе показано, как это сделать.

## Обычный процесс { #the-normal-process }

Обычный (по умолчанию) процесс выглядит так.

Приложение `FastAPI` (экземпляр) имеет метод `.openapi()`, который должен возвращать схему OpenAPI.

### OpenAPI Şemasını Üretme { #generate-the-openapi-schema }

Ardından, bir `custom_openapi()` fonksiyonunun içinde aynı yardımcı fonksiyonu kullanarak OpenAPI şemasını üretin:

{* ../../docs_src/extending_openapi/tutorial001_py310.py hl[2,15:21] *}

### OpenAPI Şemasını Değiştirme { #modify-the-openapi-schema }

# Extending OpenAPI { #extending-openapi }

There are some cases where you might need to modify the generated OpenAPI schema.

In this section you will see how.

## The normal process { #the-normal-process }

The normal (default) process, is as follows.

A `FastAPI` application (instance) has an `.openapi()` method that is expected to return the OpenAPI schema.

* Le *chemin* peut contenir une [expression OpenAPI 3](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression) (voir plus bas) où il peut utiliser des variables avec des paramètres et des parties de la requête originale envoyée à *votre API*.

### L’expression du chemin de callback { #the-callback-path-expression }

* 它不需要任何实际的代码，因为应用不会调用这段代码。它只是用于存档*外部 API*。因此，函数的内容只需要 `pass` 就可以了
* *路径*可以包含 [OpenAPI 3 表达式](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression)（详见下文），可以使用带参数的变量，以及发送至您的 API 的原始请求的部分

### 回调路径表达式 { #the-callback-path-expression }

回调*路径*支持包含发送给您的 API 的原始请求的部分的 [OpenAPI 3 表达式](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression)。

本例中是 `str`：

```Python

儘管如此，在某些特定情境下，你可能確實需要在某些環境（例如正式環境）停用 API 文件，或依據環境變數的設定來決定是否啟用。

## 透過設定與環境變數的條件式 OpenAPI { #conditional-openapi-from-settings-and-env-vars }

你可以用相同的 Pydantic 設定，來配置產生的 OpenAPI 與文件 UI。

例如：

{* ../../docs_src/conditional_openapi/tutorial001_py310.py hl[6,11] *}

這裡我們宣告 `openapi_url` 設定，預設值同樣是 `"/openapi.json"`。

接著在建立 `FastAPI` 應用時使用它。

然後你可以將環境變數 `OPENAPI_URL` 設為空字串，以停用 OpenAPI（包含文件 UI），如下：

<div class="termy">

```console

# Séparer les schémas OpenAPI pour l'entrée et la sortie ou non { #separate-openapi-schemas-for-input-and-output-or-not }

Depuis la sortie de **Pydantic v2**, l'OpenAPI généré est un peu plus précis et **correct** qu'avant. 😎

En fait, dans certains cas, il y aura même **deux schémas JSON** dans OpenAPI pour le même modèle Pydantic, pour l'entrée et pour la sortie, selon s'ils ont des **valeurs par défaut**.

## Ayarlar ve env var'lar ile koşullu OpenAPI { #conditional-openapi-from-settings-and-env-vars }

Üretilen OpenAPI'yi ve docs UI'larını yapılandırmak için aynı Pydantic settings'i kolayca kullanabilirsiniz.

Örneğin:

{* ../../docs_src/conditional_openapi/tutorial001_py310.py hl[6,11] *}

Burada `openapi_url` ayarını, varsayılanı `"/openapi.json"` olacak şekilde tanımlıyoruz.