Lorhan Sohaky
2 years ago
committed by
GitHub
GitHub
342 changed files with 1710 additions and 1008 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 |
@ -1,3 +1,6 @@ |
|||||
# Define this here and not in the main mkdocs.yml file because that one is auto |
# Define this here and not in the main mkdocs.yml file because that one is auto |
||||
# updated and written, and the script would remove the env var |
# updated and written, and the script would remove the env var |
||||
INHERIT: !ENV [INSIDERS_FILE, '../en/mkdocs.no-insiders.yml'] |
INHERIT: !ENV [INSIDERS_FILE, '../en/mkdocs.no-insiders.yml'] |
||||
|
markdown_extensions: |
||||
|
pymdownx.highlight: |
||||
|
linenums: !ENV [LINENUMS, false] |
||||
|
|||||
@ -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"] |
||||
@ -0,0 +1,115 @@ |
|||||
|
from typing import Union |
||||
|
|
||||
|
from fastapi import FastAPI |
||||
|
from fastapi.testclient import TestClient |
||||
|
from pydantic import BaseModel |
||||
|
|
||||
|
|
||||
|
class FooBaseModel(BaseModel): |
||||
|
class Config: |
||||
|
extra = "forbid" |
||||
|
|
||||
|
|
||||
|
class Foo(FooBaseModel): |
||||
|
pass |
||||
|
|
||||
|
|
||||
|
app = FastAPI() |
||||
|
|
||||
|
|
||||
|
@app.post("/") |
||||
|
async def post( |
||||
|
foo: Union[Foo, None] = None, |
||||
|
): |
||||
|
return foo |
||||
|
|
||||
|
|
||||
|
client = TestClient(app) |
||||
|
|
||||
|
|
||||
|
def test_call_invalid(): |
||||
|
response = client.post("/", json={"foo": {"bar": "baz"}}) |
||||
|
assert response.status_code == 422 |
||||
|
|
||||
|
|
||||
|
def test_call_valid(): |
||||
|
response = client.post("/", json={}) |
||||
|
assert response.status_code == 200 |
||||
|
assert response.json() == {} |
||||
|
|
||||
|
|
||||
|
def test_openapi_schema(): |
||||
|
response = client.get("/openapi.json") |
||||
|
assert response.status_code == 200, response.text |
||||
|
assert response.json() == { |
||||
|
"openapi": "3.1.0", |
||||
|
"info": {"title": "FastAPI", "version": "0.1.0"}, |
||||
|
"paths": { |
||||
|
"/": { |
||||
|
"post": { |
||||
|
"summary": "Post", |
||||
|
"operationId": "post__post", |
||||
|
"requestBody": { |
||||
|
"content": { |
||||
|
"application/json": { |
||||
|
"schema": {"$ref": "#/components/schemas/Foo"} |
||||
|
} |
||||
|
} |
||||
|
}, |
||||
|
"responses": { |
||||
|
"200": { |
||||
|
"description": "Successful Response", |
||||
|
"content": {"application/json": {"schema": {}}}, |
||||
|
}, |
||||
|
"422": { |
||||
|
"description": "Validation Error", |
||||
|
"content": { |
||||
|
"application/json": { |
||||
|
"schema": { |
||||
|
"$ref": "#/components/schemas/HTTPValidationError" |
||||
|
} |
||||
|
} |
||||
|
}, |
||||
|
}, |
||||
|
}, |
||||
|
} |
||||
|
} |
||||
|
}, |
||||
|
"components": { |
||||
|
"schemas": { |
||||
|
"Foo": { |
||||
|
"properties": {}, |
||||
|
"additionalProperties": False, |
||||
|
"type": "object", |
||||
|
"title": "Foo", |
||||
|
}, |
||||
|
"HTTPValidationError": { |
||||
|
"properties": { |
||||
|
"detail": { |
||||
|
"items": {"$ref": "#/components/schemas/ValidationError"}, |
||||
|
"type": "array", |
||||
|
"title": "Detail", |
||||
|
} |
||||
|
}, |
||||
|
"type": "object", |
||||
|
"title": "HTTPValidationError", |
||||
|
}, |
||||
|
"ValidationError": { |
||||
|
"properties": { |
||||
|
"loc": { |
||||
|
"items": { |
||||
|
"anyOf": [{"type": "string"}, {"type": "integer"}] |
||||
|
}, |
||||
|
"type": "array", |
||||
|
"title": "Location", |
||||
|
}, |
||||
|
"msg": {"type": "string", "title": "Message"}, |
||||
|
"type": {"type": "string", "title": "Error Type"}, |
||||
|
}, |
||||
|
"type": "object", |
||||
|
"required": ["loc", "msg", "type"], |
||||
|
"title": "ValidationError", |
||||
|
}, |
||||
|
} |
||||
|
}, |
||||
|
} |
||||
Some files were not shown because too many files changed in this diff
Loading…
Reference in new issue