Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork8.7k
✨ Add support for OpenAPI 3.1.0#9770
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
Merged
Uh oh!
There was an error while loading.Please reload this page.
Merged
Changes fromall commits
Commits
Show all changes
34 commits Select commitHold shift + click to select a range
fe430a2 ✨ Update OpenAPI models for JSON Schema 2020-12 and OpenAPI 3.1.0
tiangolo0ca3e13 ✨ Add support for summary and webhooks
tiangolod119dca ✨ Update JSON Schema for UploadFiles
tiangolo26d88db ⏪️ Revert making paths optional, to ensure always correctness
tiangolod37b4c2 ⏪️ Keep UploadFile as format: binary for compatibility with the rest …
tiangolof1f7058 ✨ Update version of OpenAPI generated to 3.1.0
tiangolof8a9163 ✨ Update the version of Swagger UI
tiangolo8ec891e 📝 Update docs about extending OpenAPI
tiangolo25d107c 📝 Update docs and links to refer to OpenAPI 3.1.0
tiangolob785cc9 ✨ Update logic for handling webhooks
tiangolod32539b ♻️ Update parameter functions and classes, deprecate example and make…
tiangoloe5dd6d7 ✅ Update tests for OpenAPI 3.1.0
tiangolo31f9cdf 📝 Update examples for OpenAPI metadata
tiangolo324b719 ✅ Add and update tests for OpenAPI metadata
tiangoloe394b94 📝 Add source example for webhooks
tiangoloc6649ed 📝 Update docs for metadata
tiangolodd57efa 📝 Update docs for Schema extra
tiangoloe7b42cf 📝 Add docs for webhooks
tiangolo21ce600 🔧 Add webhooks docs to MkDocs
tiangolo6823b20 ✅ Update tests for extending OpenAPI
tiangolo46b7e85 ✅ Add tests for webhooks
tiangolo5d246b2 ♻️ Refactor generation of OpenAPI and JSON Schema with params
tiangolo5a0e7f6 📝 Update source examples for field examples
tiangolob84bd0d ✅ Update tests for examples
tiangolo426a193 ➕ Make sure the minimum version of typing-extensions installed has de…
tiangoloedf493a ✏️ Fix typo in Webhooks example code
tiangoloc719570 🔥 Remove commented out code of removed nullable field
tiangolo4cf82b9 🗑️ Add deprecation warnings for example argument
tiangoloc004237 ✅ Update tests to check for deprecation warnings
tiangolo37990ea ✅ Add test for webhooks with security schemes, for coverage
tiangolo3483b4c Merge branch 'master' into openapi-3-1-0
tiangolo86886fe 🍱 Update image for metadata, with new summary
tiangolo9a60f9a 🍱 Add docs image for Webhooks
tiangoloaad9988 📝 Update docs for webhooks, add docs UI image
tiangoloFile filter
Filter by extension
Conversations
Failed to load comments.
Loading
Uh oh!
There was an error while loading.Please reload this page.
Jump to
The table of contents is too big for display.
Diff view
Diff view
Uh oh!
There was an error while loading.Please reload this page.
There are no files selected for viewing
4 changes: 2 additions & 2 deletionsdocs/en/docs/advanced/additional-responses.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
4 changes: 2 additions & 2 deletionsdocs/en/docs/advanced/behind-a-proxy.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
16 changes: 10 additions & 6 deletionsdocs/en/docs/advanced/extending-openapi.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
4 changes: 2 additions & 2 deletionsdocs/en/docs/advanced/openapi-callbacks.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
51 changes: 51 additions & 0 deletionsdocs/en/docs/advanced/openapi-webhooks.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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"> |
2 changes: 1 addition & 1 deletiondocs/en/docs/advanced/path-operation-advanced-configuration.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
Binary file modifieddocs/en/docs/img/tutorial/metadata/image01.png
Loading
Sorry, something went wrong.Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong.Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletiondocs/en/docs/tutorial/first-steps.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
15 changes: 13 additions & 2 deletionsdocs/en/docs/tutorial/metadata.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
2 changes: 1 addition & 1 deletiondocs/en/docs/tutorial/path-params.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
Oops, something went wrong.
Uh oh!
There was an error while loading.Please reload this page.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.