Movatterモバイル変換


[0]ホーム

URL:


Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Sign up
Appearance settings

✨ 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
tiangolo merged 34 commits intomasterfromopenapi-3-1-0
Jun 30, 2023
Merged
Show file tree
Hide file tree
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
tiangoloJun 29, 2023
0ca3e13
✨ Add support for summary and webhooks
tiangoloJun 29, 2023
d119dca
✨ Update JSON Schema for UploadFiles
tiangoloJun 29, 2023
26d88db
⏪️ Revert making paths optional, to ensure always correctness
tiangoloJun 29, 2023
d37b4c2
⏪️ Keep UploadFile as format: binary for compatibility with the rest …
tiangoloJun 29, 2023
f1f7058
✨ Update version of OpenAPI generated to 3.1.0
tiangoloJun 29, 2023
f8a9163
✨ Update the version of Swagger UI
tiangoloJun 29, 2023
8ec891e
📝 Update docs about extending OpenAPI
tiangoloJun 30, 2023
25d107c
📝 Update docs and links to refer to OpenAPI 3.1.0
tiangoloJun 30, 2023
b785cc9
✨ Update logic for handling webhooks
tiangoloJun 30, 2023
d32539b
♻️ Update parameter functions and classes, deprecate example and make…
tiangoloJun 30, 2023
e5dd6d7
✅ Update tests for OpenAPI 3.1.0
tiangoloJun 30, 2023
31f9cdf
📝 Update examples for OpenAPI metadata
tiangoloJun 30, 2023
324b719
✅ Add and update tests for OpenAPI metadata
tiangoloJun 30, 2023
e394b94
📝 Add source example for webhooks
tiangoloJun 30, 2023
c6649ed
📝 Update docs for metadata
tiangoloJun 30, 2023
dd57efa
📝 Update docs for Schema extra
tiangoloJun 30, 2023
e7b42cf
📝 Add docs for webhooks
tiangoloJun 30, 2023
21ce600
🔧 Add webhooks docs to MkDocs
tiangoloJun 30, 2023
6823b20
✅ Update tests for extending OpenAPI
tiangoloJun 30, 2023
46b7e85
✅ Add tests for webhooks
tiangoloJun 30, 2023
5d246b2
♻️ Refactor generation of OpenAPI and JSON Schema with params
tiangoloJun 30, 2023
5a0e7f6
📝 Update source examples for field examples
tiangoloJun 30, 2023
b84bd0d
✅ Update tests for examples
tiangoloJun 30, 2023
426a193
➕ Make sure the minimum version of typing-extensions installed has de…
tiangoloJun 30, 2023
edf493a
✏️ Fix typo in Webhooks example code
tiangoloJun 30, 2023
c719570
🔥 Remove commented out code of removed nullable field
tiangoloJun 30, 2023
4cf82b9
🗑️ Add deprecation warnings for example argument
tiangoloJun 30, 2023
c004237
✅ Update tests to check for deprecation warnings
tiangoloJun 30, 2023
37990ea
✅ Add test for webhooks with security schemes, for coverage
tiangoloJun 30, 2023
3483b4c
Merge branch 'master' into openapi-3-1-0
tiangoloJun 30, 2023
86886fe
🍱 Update image for metadata, with new summary
tiangoloJun 30, 2023
9a60f9a
🍱 Add docs image for Webhooks
tiangoloJun 30, 2023
aad9988
📝 Update docs for webhooks, add docs UI image
tiangoloJun 30, 2023
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
4 changes: 2 additions & 2 deletionsdocs/en/docs/advanced/additional-responses.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -236,5 +236,5 @@ For example:

To see what exactly you can include in the responses, you can check these sections in the OpenAPI specification:

* <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#responsesObject" class="external-link" target="_blank">OpenAPI Responses Object</a>, it includes the `Response Object`.
* <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#responseObject" class="external-link" target="_blank">OpenAPI Response Object</a>, you can include anything from this directly in each response inside your `responses` parameter. Including `description`, `headers`, `content` (inside of this is that you declare different media types and JSON Schemas), and `links`.
* <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#responsesObject" class="external-link" target="_blank">OpenAPI Responses Object</a>, it includes the `Response Object`.
* <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#responseObject" class="external-link" target="_blank">OpenAPI Response Object</a>, you can include anything from this directly in each response inside your `responses` parameter. Including `description`, `headers`, `content` (inside of this is that you declare different media types and JSON Schemas), and `links`.
4 changes: 2 additions & 2 deletionsdocs/en/docs/advanced/behind-a-proxy.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -46,7 +46,7 @@ The docs UI would also need the OpenAPI schema to declare that this API `server`

```JSON hl_lines="4-8"
{
"openapi": "3.0.2",
"openapi": "3.1.0",
// More stuff here
"servers": [
{
Expand DownExpand Up@@ -298,7 +298,7 @@ Will generate an OpenAPI schema like:

```JSON hl_lines="5-7"
{
"openapi": "3.0.2",
"openapi": "3.1.0",
// More stuff here
"servers": [
{
Expand Down
16 changes: 10 additions & 6 deletionsdocs/en/docs/advanced/extending-openapi.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -29,10 +29,14 @@ And that function `get_openapi()` receives as parameters:

* `title`: The OpenAPI title, shown in the docs.
* `version`: The version of your API, e.g. `2.5.0`.
* `openapi_version`: The version of the OpenAPI specification used. By default, the latest: `3.0.2`.
* `description`: The description of your API.
* `openapi_version`: The version of the OpenAPI specification used. By default, the latest: `3.1.0`.
* `summary`: A short summary of the API.
* `description`: The description of your API, this can include markdown and will be shown in the docs.
* `routes`: A list of routes, these are each of the registered *path operations*. They are taken from `app.routes`.

!!! info
The parameter `summary` is available in OpenAPI 3.1.0 and above, supported by FastAPI 0.99.0 and above.

## Overriding the defaults

Using the information above, you can use the same utility function to generate the OpenAPI schema and override each part that you need.
Expand All@@ -51,15 +55,15 @@ First, write all your **FastAPI** application as normally:

Then, use the same utility function to generate the OpenAPI schema, inside a `custom_openapi()` function:

```Python hl_lines="2 15-20"
```Python hl_lines="2 15-21"
{!../../../docs_src/extending_openapi/tutorial001.py!}
```

### Modify the OpenAPI schema

Now you can add the ReDoc extension, adding a custom `x-logo` to the `info` "object" in the OpenAPI schema:

```Python hl_lines="21-23"
```Python hl_lines="22-24"
{!../../../docs_src/extending_openapi/tutorial001.py!}
```

Expand All@@ -71,15 +75,15 @@ That way, your application won't have to generate the schema every time a user o

It will be generated only once, and then the same cached schema will be used for the next requests.

```Python hl_lines="13-1424-25"
```Python hl_lines="13-1425-26"
{!../../../docs_src/extending_openapi/tutorial001.py!}
```

### Override the method

Now you can replace the `.openapi()` method with your new function.

```Python hl_lines="28"
```Python hl_lines="29"
{!../../../docs_src/extending_openapi/tutorial001.py!}
```

Expand Down
4 changes: 2 additions & 2 deletionsdocs/en/docs/advanced/openapi-callbacks.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -103,11 +103,11 @@ It should look just like a normal FastAPI *path operation*:
There are 2 main differences from a normal *path operation*:

* It doesn't need to have any actual code, because your app will never call this code. It's only used to document the *external API*. So, the function could just have `pass`.
* The *path* can contain an <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#key-expression" class="external-link" target="_blank">OpenAPI 3 expression</a> (see more below) where it can use variables with parameters and parts of the original request sent to *your API*.
* The *path* can contain an <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression" class="external-link" target="_blank">OpenAPI 3 expression</a> (see more below) where it can use variables with parameters and parts of the original request sent to *your API*.

### The callback path expression

The callback *path* can have an <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#key-expression" class="external-link" target="_blank">OpenAPI 3 expression</a> that can contain parts of the original request sent to *your API*.
The callback *path* can have an <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression" class="external-link" target="_blank">OpenAPI 3 expression</a> that can contain parts of the original request sent to *your API*.

In this case, it's the `str`:

Expand Down
51 changes: 51 additions & 0 deletionsdocs/en/docs/advanced/openapi-webhooks.md
View file
Open in desktop
Original file line numberDiff line numberDiff 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">
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -97,7 +97,7 @@ And if you see the resulting OpenAPI (at `/openapi.json` in your API), you will

```JSON hl_lines="22"
{
"openapi": "3.0.2",
"openapi": "3.1.0",
"info": {
"title": "FastAPI",
"version": "0.1.0"
Expand Down
Binary file modifieddocs/en/docs/img/tutorial/metadata/image01.png
View file
Open in desktop
Loading
Sorry, something went wrong.Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View file
Open in desktop
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
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -99,7 +99,7 @@ It will show a JSON starting with something like:

```JSON
{
"openapi": "3.0.2",
"openapi": "3.1.0",
"info": {
"title": "FastAPI",
"version": "0.1.0"
Expand Down
15 changes: 13 additions & 2 deletionsdocs/en/docs/tutorial/metadata.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -9,15 +9,16 @@ You can set the following fields that are used in the OpenAPI specification and
| Parameter | Type | Description |
|------------|------|-------------|
| `title` | `str` | The title of the API. |
| `summary` | `str` | A short summary of the API. <small>Available since OpenAPI 3.1.0, FastAPI 0.99.0.</small> |
| `description` | `str` | A short description of the API. It can use Markdown. |
| `version` | `string` | The version of the API. This is the version of your own application, not of OpenAPI. For example `2.5.0`. |
| `terms_of_service` | `str` | A URL to the Terms of Service for the API. If provided, this has to be a URL. |
| `contact` | `dict` | The contact information for the exposed API. It can contain several fields. <details><summary><code>contact</code> fields</summary><table><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>name</code></td><td><code>str</code></td><td>The identifying name of the contact person/organization.</td></tr><tr><td><code>url</code></td><td><code>str</code></td><td>The URL pointing to the contact information. MUST be in the format of a URL.</td></tr><tr><td><code>email</code></td><td><code>str</code></td><td>The email address of the contact person/organization. MUST be in the format of an email address.</td></tr></tbody></table></details> |
| `license_info` | `dict` | The license information for the exposed API. It can contain several fields. <details><summary><code>license_info</code> fields</summary><table><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>name</code></td><td><code>str</code></td><td><strong>REQUIRED</strong> (if a <code>license_info</code> is set). The license name used for the API.</td></tr><tr><td><code>url</code></td><td><code>str</code></td><td>A URL to the license used for the API. MUST be in the format of a URL.</td></tr></tbody></table></details> |
| `license_info` | `dict` | The license information for the exposed API. It can contain several fields. <details><summary><code>license_info</code> fields</summary><table><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>name</code></td><td><code>str</code></td><td><strong>REQUIRED</strong> (if a <code>license_info</code> is set). The license name used for the API.</td></tr><tr><td><code>identifier</code></td><td><code>str</code></td><td>An <a href="https://spdx.dev/spdx-specification-21-web-version/#h.jxpfx0ykyb60" class="external-link" target="_blank">SPDX</a> license expression for the API. The <code>identifier</code> field is mutually exclusive of the <code>url</code> field. <small>Available since OpenAPI 3.1.0, FastAPI 0.99.0.</small></td></tr><tr><td><code>url</code></td><td><code>str</code></td><td>A URL to the license used for the API. MUST be in the format of a URL.</td></tr></tbody></table></details> |

You can set them as follows:

```Python hl_lines="3-16 19-31"
```Python hl_lines="3-16 19-32"
{!../../../docs_src/metadata/tutorial001.py!}
```

Expand All@@ -28,6 +29,16 @@ With this configuration, the automatic API docs would look like:

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

## License identifier

Since OpenAPI 3.1.0 and FastAPI 0.99.0, you can also set the `license_info` with an `identifier` instead of a `url`.

For example:

```Python hl_lines="31"
{!../../../docs_src/metadata/tutorial001_1.py!}
```

## Metadata for tags

You can also add additional metadata for the different tags used to group your path operations with the parameter `openapi_tags`.
Expand Down
2 changes: 1 addition & 1 deletiondocs/en/docs/tutorial/path-params.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -83,7 +83,7 @@ And when you open your browser at <a href="http://127.0.0.1:8000/docs" class="ex

## Standards-based benefits, alternative documentation

And because the generated schema is from the <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md" class="external-link" target="_blank">OpenAPI</a> standard, there are many compatible tools.
And because the generated schema is from the <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md" class="external-link" target="_blank">OpenAPI</a> standard, there are many compatible tools.

Because of this, **FastAPI** itself provides an alternative API documentation (using ReDoc), which you can access at <a href="http://127.0.0.1:8000/redoc" class="external-link" target="_blank">http://127.0.0.1:8000/redoc</a>:

Expand Down
Loading

[8]ページ先頭

©2009-2026 Movatter.jp