Browse Source
* ✨ Update OpenAPI models for JSON Schema 2020-12 and OpenAPI 3.1.0 * ✨ Add support for summary and webhooks * ✨ Update JSON Schema for UploadFiles * ⏪️ Revert making paths optional, to ensure always correctness * ⏪️ Keep UploadFile as format: binary for compatibility with the rest of Pydantic bytes fields in v1 * ✨ Update version of OpenAPI generated to 3.1.0 * ✨ Update the version of Swagger UI * 📝 Update docs about extending OpenAPI * 📝 Update docs and links to refer to OpenAPI 3.1.0 * ✨ Update logic for handling webhooks * ♻️ Update parameter functions and classes, deprecate example and make examples the main field * ✅ Update tests for OpenAPI 3.1.0 * 📝 Update examples for OpenAPI metadata * ✅ Add and update tests for OpenAPI metadata * 📝 Add source example for webhooks * 📝 Update docs for metadata * 📝 Update docs for Schema extra * 📝 Add docs for webhooks * 🔧 Add webhooks docs to MkDocs * ✅ Update tests for extending OpenAPI * ✅ Add tests for webhooks * ♻️ Refactor generation of OpenAPI and JSON Schema with params * 📝 Update source examples for field examples * ✅ Update tests for examples * ➕ Make sure the minimum version of typing-extensions installed has deprecated() (already a dependency of Pydantic) * ✏️ Fix typo in Webhooks example code * 🔥 Remove commented out code of removed nullable field * 🗑️ Add deprecation warnings for example argument * ✅ Update tests to check for deprecation warnings * ✅ Add test for webhooks with security schemes, for coverage * 🍱 Update image for metadata, with new summary * 🍱 Add docs image for Webhooks * 📝 Update docs for webhooks, add docs UI imagepull/9775/head
Sebastián Ramírez
2 years ago
committed by
GitHub
GitHub
335 changed files with 1564 additions and 922 deletions
@ -0,0 +1,51 @@ |
|||
# OpenAPI Webhooks |
|||
|
|||
There are cases where you want to tell your API **users** that your app could call *their* app (sending a request) with some data, normally to **notify** of some type of **event**. |
|||
|
|||
This means that instead of the normal process of your users sending requests to your API, it's **your API** (or your app) that could **send requests to their system** (to their API, their app). |
|||
|
|||
This is normally called a **webhook**. |
|||
|
|||
## Webhooks steps |
|||
|
|||
The process normally is that **you define** in your code what is the message that you will send, the **body of the request**. |
|||
|
|||
You also define in some way at which **moments** your app will send those requests or events. |
|||
|
|||
And **your users** define in some way (for example in a web dashboard somewhere) the **URL** where your app should send those requests. |
|||
|
|||
All the **logic** about how to register the URLs for webhooks and the code to actually send those requests is up to you. You write it however you want to in **your own code**. |
|||
|
|||
## Documenting webhooks with **FastAPI** and OpenAPI |
|||
|
|||
With **FastAPI**, using OpenAPI, you can define the names of these webhooks, the types of HTTP operations that your app can send (e.g. `POST`, `PUT`, etc.) and the request **bodies** that your app would send. |
|||
|
|||
This can make it a lot easier for your users to **implement their APIs** to receive your **webhook** requests, they might even be able to autogenerate some of their own API code. |
|||
|
|||
!!! info |
|||
Webhooks are available in OpenAPI 3.1.0 and above, supported by FastAPI `0.99.0` and above. |
|||
|
|||
## An app with webhooks |
|||
|
|||
When you create a **FastAPI** application, there is a `webhooks` attribute that you can use to define *webhooks*, the same way you would define *path operations*, for example with `@app.webhooks.post()`. |
|||
|
|||
```Python hl_lines="9-13 36-53" |
|||
{!../../../docs_src/openapi_webhooks/tutorial001.py!} |
|||
``` |
|||
|
|||
The webhooks that you define will end up in the **OpenAPI** schema and the automatic **docs UI**. |
|||
|
|||
!!! info |
|||
The `app.webhooks` object is actually just an `APIRouter`, the same type you would use when structuring your app with multiple files. |
|||
|
|||
Notice that with webhooks you are actually not declaring a *path* (like `/items/`), the text you pass there is just an **identifier** of the webhook (the name of the event), for example in `@app.webhooks.post("new-subscription")`, the webhook name is `new-subscription`. |
|||
|
|||
This is because it is expected that **your users** would define the actual **URL path** where they want to receive the webhook request in some other way (e.g. a web dashboard). |
|||
|
|||
### Check the docs |
|||
|
|||
Now you can start your app with Uvicorn and go to <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>. |
|||
|
|||
You will see your docs have the normal *path operations* and now also some **webhooks**: |
|||
|
|||
<img src="/img/tutorial/openapi-webhooks/image01.png"> |
|||
|
Before Width: | Height: | Size: 88 KiB After Width: | Height: | Size: 84 KiB |
|
After Width: | Height: | Size: 85 KiB |
@ -0,0 +1,38 @@ |
|||
from fastapi import FastAPI |
|||
|
|||
description = """ |
|||
ChimichangApp API helps you do awesome stuff. 🚀 |
|||
|
|||
## Items |
|||
|
|||
You can **read items**. |
|||
|
|||
## Users |
|||
|
|||
You will be able to: |
|||
|
|||
* **Create users** (_not implemented_). |
|||
* **Read users** (_not implemented_). |
|||
""" |
|||
|
|||
app = FastAPI( |
|||
title="ChimichangApp", |
|||
description=description, |
|||
summary="Deadpool's favorite app. Nuff said.", |
|||
version="0.0.1", |
|||
terms_of_service="http://example.com/terms/", |
|||
contact={ |
|||
"name": "Deadpoolio the Amazing", |
|||
"url": "http://x-force.example.com/contact/", |
|||
"email": "[email protected]", |
|||
}, |
|||
license_info={ |
|||
"name": "Apache 2.0", |
|||
"identifier": "MIT", |
|||
}, |
|||
) |
|||
|
|||
|
|||
@app.get("/items/") |
|||
async def read_items(): |
|||
return [{"name": "Katana"}] |
|||
@ -0,0 +1,25 @@ |
|||
from datetime import datetime |
|||
|
|||
from fastapi import FastAPI |
|||
from pydantic import BaseModel |
|||
|
|||
app = FastAPI() |
|||
|
|||
|
|||
class Subscription(BaseModel): |
|||
username: str |
|||
montly_fee: float |
|||
start_date: datetime |
|||
|
|||
|
|||
@app.webhooks.post("new-subscription") |
|||
def new_subscription(body: Subscription): |
|||
""" |
|||
When a new user subscribes to your service we'll send you a POST request with this |
|||
data to the URL that you register for the event `new-subscription` in the dashboard. |
|||
""" |
|||
|
|||
|
|||
@app.get("/users/") |
|||
def read_users(): |
|||
return ["Rick", "Morty"] |
|||
Some files were not shown because too many files changed in this diff
Loading…
Reference in new issue