Lorhan Sohaky
2 years ago
73 changed files with 5967 additions and 166 deletions
@ -0,0 +1,231 @@ |
|||
# Separate OpenAPI Schemas for Input and Output or Not |
|||
|
|||
When using **Pydantic v2**, the generated OpenAPI is a bit more exact and **correct** than before. 😎 |
|||
|
|||
In fact, in some cases, it will even have **two JSON Schemas** in OpenAPI for the same Pydantic model, for input and output, depending on if they have **default values**. |
|||
|
|||
Let's see how that works and how to change it if you need to do that. |
|||
|
|||
## Pydantic Models for Input and Output |
|||
|
|||
Let's say you have a Pydantic model with default values, like this one: |
|||
|
|||
=== "Python 3.10+" |
|||
|
|||
```Python hl_lines="7" |
|||
{!> ../../../docs_src/separate_openapi_schemas/tutorial001_py310.py[ln:1-7]!} |
|||
|
|||
# Code below omitted 👇 |
|||
``` |
|||
|
|||
<details> |
|||
<summary>👀 Full file preview</summary> |
|||
|
|||
```Python |
|||
{!> ../../../docs_src/separate_openapi_schemas/tutorial001_py310.py!} |
|||
``` |
|||
|
|||
</details> |
|||
|
|||
=== "Python 3.9+" |
|||
|
|||
```Python hl_lines="9" |
|||
{!> ../../../docs_src/separate_openapi_schemas/tutorial001_py39.py[ln:1-9]!} |
|||
|
|||
# Code below omitted 👇 |
|||
``` |
|||
|
|||
<details> |
|||
<summary>👀 Full file preview</summary> |
|||
|
|||
```Python |
|||
{!> ../../../docs_src/separate_openapi_schemas/tutorial001_py39.py!} |
|||
``` |
|||
|
|||
</details> |
|||
|
|||
=== "Python 3.7+" |
|||
|
|||
```Python hl_lines="9" |
|||
{!> ../../../docs_src/separate_openapi_schemas/tutorial001.py[ln:1-9]!} |
|||
|
|||
# Code below omitted 👇 |
|||
``` |
|||
|
|||
<details> |
|||
<summary>👀 Full file preview</summary> |
|||
|
|||
```Python |
|||
{!> ../../../docs_src/separate_openapi_schemas/tutorial001.py!} |
|||
``` |
|||
|
|||
</details> |
|||
|
|||
### Model for Input |
|||
|
|||
If you use this model as an input like here: |
|||
|
|||
=== "Python 3.10+" |
|||
|
|||
```Python hl_lines="14" |
|||
{!> ../../../docs_src/separate_openapi_schemas/tutorial001_py310.py[ln:1-15]!} |
|||
|
|||
# Code below omitted 👇 |
|||
``` |
|||
|
|||
<details> |
|||
<summary>👀 Full file preview</summary> |
|||
|
|||
```Python |
|||
{!> ../../../docs_src/separate_openapi_schemas/tutorial001_py310.py!} |
|||
``` |
|||
|
|||
</details> |
|||
|
|||
=== "Python 3.9+" |
|||
|
|||
```Python hl_lines="16" |
|||
{!> ../../../docs_src/separate_openapi_schemas/tutorial001_py39.py[ln:1-17]!} |
|||
|
|||
# Code below omitted 👇 |
|||
``` |
|||
|
|||
<details> |
|||
<summary>👀 Full file preview</summary> |
|||
|
|||
```Python |
|||
{!> ../../../docs_src/separate_openapi_schemas/tutorial001_py39.py!} |
|||
``` |
|||
|
|||
</details> |
|||
|
|||
=== "Python 3.7+" |
|||
|
|||
```Python hl_lines="16" |
|||
{!> ../../../docs_src/separate_openapi_schemas/tutorial001.py[ln:1-17]!} |
|||
|
|||
# Code below omitted 👇 |
|||
``` |
|||
|
|||
<details> |
|||
<summary>👀 Full file preview</summary> |
|||
|
|||
```Python |
|||
{!> ../../../docs_src/separate_openapi_schemas/tutorial001.py!} |
|||
``` |
|||
|
|||
</details> |
|||
|
|||
...then the `description` field will **not be required**. Because it has a default value of `None`. |
|||
|
|||
### Input Model in Docs |
|||
|
|||
You can confirm that in the docs, the `description` field doesn't have a **red asterisk**, it's not marked as required: |
|||
|
|||
<div class="screenshot"> |
|||
<img src="/img/tutorial/separate-openapi-schemas/image01.png"> |
|||
</div> |
|||
|
|||
### Model for Output |
|||
|
|||
But if you use the same model as an output, like here: |
|||
|
|||
=== "Python 3.10+" |
|||
|
|||
```Python hl_lines="19" |
|||
{!> ../../../docs_src/separate_openapi_schemas/tutorial001_py310.py!} |
|||
``` |
|||
|
|||
=== "Python 3.9+" |
|||
|
|||
```Python hl_lines="21" |
|||
{!> ../../../docs_src/separate_openapi_schemas/tutorial001_py39.py!} |
|||
``` |
|||
|
|||
=== "Python 3.7+" |
|||
|
|||
```Python hl_lines="21" |
|||
{!> ../../../docs_src/separate_openapi_schemas/tutorial001.py!} |
|||
``` |
|||
|
|||
...then because `description` has a default value, if you **don't return anything** for that field, it will still have that **default value**. |
|||
|
|||
### Model for Output Response Data |
|||
|
|||
If you interact with the docs and check the response, even though the code didn't add anything in one of the `description` fields, the JSON response contains the default value (`null`): |
|||
|
|||
<div class="screenshot"> |
|||
<img src="/img/tutorial/separate-openapi-schemas/image02.png"> |
|||
</div> |
|||
|
|||
This means that it will **always have a value**, it's just that sometimes the value could be `None` (or `null` in JSON). |
|||
|
|||
That means that, clients using your API don't have to check if the value exists or not, they can **assume the field will always be there**, but just that in some cases it will have the default value of `None`. |
|||
|
|||
The way to describe this in OpenAPI, is to mark that field as **required**, because it will always be there. |
|||
|
|||
Because of that, the JSON Schema for a model can be different depending on if it's used for **input or output**: |
|||
|
|||
* for **input** the `description` will **not be required** |
|||
* for **output** it will be **required** (and possibly `None`, or in JSON terms, `null`) |
|||
|
|||
### Model for Output in Docs |
|||
|
|||
You can check the output model in the docs too, **both** `name` and `description` are marked as **required** with a **red asterisk**: |
|||
|
|||
<div class="screenshot"> |
|||
<img src="/img/tutorial/separate-openapi-schemas/image03.png"> |
|||
</div> |
|||
|
|||
### Model for Input and Output in Docs |
|||
|
|||
And if you check all the available Schemas (JSON Schemas) in OpenAPI, you will see that there are two, one `Item-Input` and one `Item-Output`. |
|||
|
|||
For `Item-Input`, `description` is **not required**, it doesn't have a red asterisk. |
|||
|
|||
But for `Item-Output`, `description` is **required**, it has a red asterisk. |
|||
|
|||
<div class="screenshot"> |
|||
<img src="/img/tutorial/separate-openapi-schemas/image04.png"> |
|||
</div> |
|||
|
|||
With this feature from **Pydantic v2**, your API documentation is more **precise**, and if you have autogenerated clients and SDKs, they will be more precise too, with a better **developer experience** and consistency. 🎉 |
|||
|
|||
## Do not Separate Schemas |
|||
|
|||
Now, there are some cases where you might want to have the **same schema for input and output**. |
|||
|
|||
Probably the main use case for this is if you already have some autogenerated client code/SDKs and you don't want to update all the autogenerated client code/SDKs yet, you probably will want to do it at some point, but maybe not right now. |
|||
|
|||
In that case, you can disable this feature in **FastAPI**, with the parameter `separate_input_output_schemas=False`. |
|||
|
|||
!!! info |
|||
Support for `separate_input_output_schemas` was added in FastAPI `0.102.0`. 🤓 |
|||
|
|||
=== "Python 3.10+" |
|||
|
|||
```Python hl_lines="10" |
|||
{!> ../../../docs_src/separate_openapi_schemas/tutorial002_py310.py!} |
|||
``` |
|||
|
|||
=== "Python 3.9+" |
|||
|
|||
```Python hl_lines="12" |
|||
{!> ../../../docs_src/separate_openapi_schemas/tutorial002_py39.py!} |
|||
``` |
|||
|
|||
=== "Python 3.7+" |
|||
|
|||
```Python hl_lines="12" |
|||
{!> ../../../docs_src/separate_openapi_schemas/tutorial002.py!} |
|||
``` |
|||
|
|||
### Same Schema for Input and Output Models in Docs |
|||
|
|||
And now there will be one single schema for input and output for the model, only `Item`, and it will have `description` as **not required**: |
|||
|
|||
<div class="screenshot"> |
|||
<img src="/img/tutorial/separate-openapi-schemas/image05.png"> |
|||
</div> |
|||
|
|||
This is the same behavior as in Pydantic v1. 🤓 |
|||
|
After Width: | Height: | Size: 9.9 KiB |
|
After Width: | Height: | Size: 18 KiB |
|
After Width: | Height: | Size: 80 KiB |
|
After Width: | Height: | Size: 90 KiB |
|
After Width: | Height: | Size: 83 KiB |
|
After Width: | Height: | Size: 57 KiB |
|
After Width: | Height: | Size: 44 KiB |
@ -0,0 +1,412 @@ |
|||
# Альтернативи, натхнення та порівняння |
|||
|
|||
Що надихнуло на створення **FastAPI**, який він у порінянні з іншими альтернативами та чого він у них навчився. |
|||
|
|||
## Вступ |
|||
|
|||
**FastAPI** не існувало б, якби не попередні роботи інших. |
|||
|
|||
Раніше було створено багато інструментів, які надихнули на його створення. |
|||
|
|||
Я кілька років уникав створення нового фреймворку. Спочатку я спробував вирішити всі функції, охоплені **FastAPI**, використовуючи багато різних фреймворків, плагінів та інструментів. |
|||
|
|||
Але в якийсь момент не було іншого виходу, окрім створення чогось, що надавало б усі ці функції, взявши найкращі ідеї з попередніх інструментів і поєднавши їх найкращим чином, використовуючи мовні функції, які навіть не були доступні раніше (Python 3.6+ підказки типів). |
|||
|
|||
## Попередні інструменти |
|||
|
|||
### <a href="https://www.djangoproject.com/" class="external-link" target="_blank">Django</a> |
|||
|
|||
Це найпопулярніший фреймворк Python, який користується широкою довірою. Він використовується для створення таких систем, як Instagram. |
|||
|
|||
Він відносно тісно пов’язаний з реляційними базами даних (наприклад, MySQL або PostgreSQL), тому мати базу даних NoSQL (наприклад, Couchbase, MongoDB, Cassandra тощо) як основний механізм зберігання не дуже просто. |
|||
|
|||
Він був створений для створення HTML у серверній частині, а не для створення API, які використовуються сучасним інтерфейсом (як-от React, Vue.js і Angular) або іншими системами (як-от <abbr title="Internet of Things">IoT</abbr > пристрої), які спілкуються з ним. |
|||
|
|||
### <a href="https://www.django-rest-framework.org/" class="external-link" target="_blank">Django REST Framework</a> |
|||
|
|||
Фреймворк Django REST був створений як гнучкий інструментарій для створення веб-інтерфейсів API використовуючи Django в основі, щоб покращити його можливості API. |
|||
|
|||
Його використовують багато компаній, включаючи Mozilla, Red Hat і Eventbrite. |
|||
|
|||
Це був один із перших прикладів **автоматичної документації API**, і саме це була одна з перших ідей, яка надихнула на «пошук» **FastAPI**. |
|||
|
|||
!!! Примітка |
|||
Django REST Framework створив Том Крісті. Той самий творець Starlette і Uvicorn, на яких базується **FastAPI**. |
|||
|
|||
|
|||
!!! Перегляньте "Надихнуло **FastAPI** на" |
|||
Мати автоматичний веб-інтерфейс документації API. |
|||
|
|||
### <a href="https://flask.palletsprojects.com" class="external-link" target="_blank">Flask</a> |
|||
|
|||
Flask — це «мікрофреймворк», він не включає інтеграцію бази даних, а також багато речей, які за замовчуванням є в Django. |
|||
|
|||
Ця простота та гнучкість дозволяють використовувати бази даних NoSQL як основну систему зберігання даних. |
|||
|
|||
Оскільки він дуже простий, він порівняно легкий та інтуїтивний для освоєння, хоча в деяких моментах документація стає дещо технічною. |
|||
|
|||
Він також зазвичай використовується для інших програм, яким не обов’язково потрібна база даних, керування користувачами або будь-яка з багатьох функцій, які є попередньо вбудованими в Django. Хоча багато з цих функцій можна додати за допомогою плагінів. |
|||
|
|||
Відокремлення частин було ключовою особливістю, яку я хотів зберегти, при цьому залишаючись «мікрофреймворком», який можна розширити, щоб охопити саме те, що потрібно. |
|||
|
|||
Враховуючи простоту Flask, він здавався хорошим підходом для створення API. Наступним, що знайшов, був «Django REST Framework» для Flask. |
|||
|
|||
!!! Переглянте "Надихнуло **FastAPI** на" |
|||
Бути мікрофреймоворком. Зробити легким комбінування та поєднання необхідних інструментів та частин. |
|||
|
|||
Мати просту та легку у використанні систему маршрутизації. |
|||
|
|||
|
|||
### <a href="https://requests.readthedocs.io" class="external-link" target="_blank">Requests</a> |
|||
|
|||
**FastAPI** насправді не є альтернативою **Requests**. Сфера їх застосування дуже різна. |
|||
|
|||
Насправді цілком звична річ використовувати Requests *всередині* програми FastAPI. |
|||
|
|||
Але все ж FastAPI черпав натхнення з Requests. |
|||
|
|||
**Requests** — це бібліотека для *взаємодії* з API (як клієнт), а **FastAPI** — це бібліотека для *створення* API (як сервер). |
|||
|
|||
Вони більш-менш знаходяться на протилежних кінцях, доповнюючи одна одну. |
|||
|
|||
Requests мають дуже простий та інтуїтивно зрозумілий дизайн, дуже простий у використанні, з розумними параметрами за замовчуванням. Але в той же час він дуже потужний і налаштовується. |
|||
|
|||
Ось чому, як сказано на офіційному сайті: |
|||
|
|||
> Requests є одним із найбільш завантажуваних пакетів Python усіх часів |
|||
|
|||
Використовувати його дуже просто. Наприклад, щоб виконати запит `GET`, ви повинні написати: |
|||
|
|||
```Python |
|||
response = requests.get("http://example.com/some/url") |
|||
``` |
|||
|
|||
Відповідна операція *роуту* API FastAPI може виглядати так: |
|||
|
|||
```Python hl_lines="1" |
|||
@app.get("/some/url") |
|||
def read_url(): |
|||
return {"message": "Hello World"} |
|||
``` |
|||
|
|||
Зверніть увагу на схожість у `requests.get(...)` і `@app.get(...)`. |
|||
|
|||
!!! Перегляньте "Надихнуло **FastAPI** на" |
|||
* Майте простий та інтуїтивно зрозумілий API. |
|||
* Використовуйте імена (операції) методів HTTP безпосередньо, простим та інтуїтивно зрозумілим способом. |
|||
* Розумні параметри за замовчуванням, але потужні налаштування. |
|||
|
|||
|
|||
### <a href="https://swagger.io/" class="external-link" target="_blank">Swagger</a> / <a href="https://github.com/OAI /OpenAPI-Specification/" class="external-link" target="_blank">OpenAPI</a> |
|||
|
|||
Головною функцією, яку я хотів від Django REST Framework, була автоматична API документація. |
|||
|
|||
Потім я виявив, що існує стандарт для документування API з використанням JSON (або YAML, розширення JSON) під назвою Swagger. |
|||
|
|||
І вже був створений веб-інтерфейс користувача для Swagger API. Отже, можливість генерувати документацію Swagger для API дозволить використовувати цей веб-інтерфейс автоматично. |
|||
|
|||
У якийсь момент Swagger було передано Linux Foundation, щоб перейменувати його на OpenAPI. |
|||
|
|||
Тому, коли говорять про версію 2.0, прийнято говорити «Swagger», а про версію 3+ «OpenAPI». |
|||
|
|||
!!! Перегляньте "Надихнуло **FastAPI** на" |
|||
Прийняти і використовувати відкритий стандарт для специфікацій API замість спеціальної схеми. |
|||
|
|||
Інтегрувати інструменти інтерфейсу на основі стандартів: |
|||
|
|||
* <a href="https://github.com/swagger-api/swagger-ui" class="external-link" target="_blank">Інтерфейс Swagger</a> |
|||
* <a href="https://github.com/Rebilly/ReDoc" class="external-link" target="_blank">ReDoc</a> |
|||
|
|||
Ці два було обрано через те, що вони досить популярні та стабільні, але, виконавши швидкий пошук, ви можете знайти десятки додаткових альтернативних інтерфейсів для OpenAPI (які можна використовувати з **FastAPI**). |
|||
|
|||
### Фреймворки REST для Flask |
|||
|
|||
Існує кілька фреймворків Flask REST, але, витративши час і роботу на їх дослідження, я виявив, що багато з них припинено або залишено, з кількома постійними проблемами, які зробили їх непридатними. |
|||
|
|||
### <a href="https://marshmallow.readthedocs.io/en/stable/" class="external-link" target="_blank">Marshmallow</a> |
|||
|
|||
Однією з головних функцій, необхідних для систем API, є "<abbr title="також звана marshalling, conversion">серіалізація</abbr>", яка бере дані з коду (Python) і перетворює їх на щось, що можна надіслати через мережу. Наприклад, перетворення об’єкта, що містить дані з бази даних, на об’єкт JSON. Перетворення об’єктів `datetime` на строки тощо. |
|||
|
|||
Іншою важливою функцією, необхідною для API, є перевірка даних, яка забезпечує дійсність даних за певними параметрами. Наприклад, що деяке поле є `int`, а не деяка випадкова строка. Це особливо корисно для вхідних даних. |
|||
|
|||
Без системи перевірки даних вам довелося б виконувати всі перевірки вручну, у коді. |
|||
|
|||
Marshmallow створено для забезпечення цих функцій. Це чудова бібліотека, і я часто нею користувався раніше. |
|||
|
|||
Але він був створений до того, як існували підказки типу Python. Отже, щоб визначити кожну <abbr title="визначення того, як дані повинні бути сформовані">схему</abbr>, вам потрібно використовувати спеціальні утиліти та класи, надані Marshmallow. |
|||
|
|||
!!! Перегляньте "Надихнуло **FastAPI** на" |
|||
Використовувати код для автоматичного визначення "схем", які надають типи даних і перевірку. |
|||
|
|||
### <a href="https://webargs.readthedocs.io/en/latest/" class="external-link" target="_blank">Webargs</a> |
|||
|
|||
Іншою важливою функцією, необхідною для API, є <abbr title="читання та перетворення даних Python">аналіз</abbr> даних із вхідних запитів. |
|||
|
|||
Webargs — це інструмент, створений, щоб забезпечити це поверх кількох фреймворків, включаючи Flask. |
|||
|
|||
Він використовує Marshmallow в основі для перевірки даних. І створений тими ж розробниками. |
|||
|
|||
Це чудовий інструмент, і я також часто використовував його, перш ніж створити **FastAPI**. |
|||
|
|||
!!! Інформація |
|||
Webargs був створений тими ж розробниками Marshmallow. |
|||
|
|||
!!! Перегляньте "Надихнуло **FastAPI** на" |
|||
Мати автоматичну перевірку даних вхідного запиту. |
|||
|
|||
### <a href="https://apispec.readthedocs.io/en/stable/" class="external-link" target="_blank">APISpec</a> |
|||
|
|||
Marshmallow і Webargs забезпечують перевірку, аналіз і серіалізацію як плагіни. |
|||
|
|||
Але документація досі відсутня. Потім було створено APISpec. |
|||
|
|||
Це плагін для багатьох фреймворків (також є плагін для Starlette). |
|||
|
|||
Принцип роботи полягає в тому, що ви пишете визначення схеми, використовуючи формат YAML, у docstring кожної функції, що обробляє маршрут. |
|||
|
|||
І він генерує схеми OpenAPI. |
|||
|
|||
Так це працює у Flask, Starlette, Responder тощо. |
|||
|
|||
Але потім ми знову маємо проблему наявності мікросинтаксису всередині Python строки (великий YAML). |
|||
|
|||
Редактор тут нічим не може допомогти. І якщо ми змінимо параметри чи схеми Marshmallow і забудемо також змінити цю строку документа YAML, згенерована схема буде застарілою. |
|||
|
|||
!!! Інформація |
|||
APISpec був створений тими ж розробниками Marshmallow. |
|||
|
|||
|
|||
!!! Перегляньте "Надихнуло **FastAPI** на" |
|||
Підтримувати відкритий стандарт API, OpenAPI. |
|||
|
|||
### <a href="https://flask-apispec.readthedocs.io/en/latest/" class="external-link" target="_blank">Flask-apispec</a> |
|||
|
|||
Це плагін Flask, який об’єднує Webargs, Marshmallow і APISpec. |
|||
|
|||
Він використовує інформацію з Webargs і Marshmallow для автоматичного створення схем OpenAPI за допомогою APISpec. |
|||
|
|||
Це чудовий інструмент, дуже недооцінений. Він має бути набагато популярнішим, ніж багато плагінів Flask. Це може бути пов’язано з тим, що його документація надто стисла й абстрактна. |
|||
|
|||
Це вирішило необхідність писати YAML (інший синтаксис) всередині рядків документів Python. |
|||
|
|||
Ця комбінація Flask, Flask-apispec із Marshmallow і Webargs була моїм улюбленим бекенд-стеком до створення **FastAPI**. |
|||
|
|||
Їі використання призвело до створення кількох генераторів повного стека Flask. Це основний стек, який я (та кілька зовнішніх команд) використовував досі: |
|||
|
|||
* <a href="https://github.com/tiangolo/full-stack" class="external-link" target="_blank">https://github.com/tiangolo/full-stack</a> |
|||
* <a href="https://github.com/tiangolo/full-stack-flask-couchbase" class="external-link" target="_blank">https://github.com/tiangolo/full-stack-flask-couchbase</a> |
|||
* <a href="https://github.com/tiangolo/full-stack-flask-couchdb" class="external-link" target="_blank">https://github.com/tiangolo/full-stack-flask-couchdb</a> |
|||
|
|||
І ці самі генератори повного стеку були основою [**FastAPI** генераторів проектів](project-generation.md){.internal-link target=_blank}. |
|||
|
|||
!!! Інформація |
|||
Flask-apispec був створений тими ж розробниками Marshmallow. |
|||
|
|||
!!! Перегляньте "Надихнуло **FastAPI** на" |
|||
Створення схеми OpenAPI автоматично з того самого коду, який визначає серіалізацію та перевірку. |
|||
|
|||
### <a href="https://nestjs.com/" class="external-link" target="_blank">NestJS</a> (та <a href="https://angular.io/ " class="external-link" target="_blank">Angular</a>) |
|||
|
|||
Це навіть не Python, NestJS — це фреймворк NodeJS JavaScript (TypeScript), натхненний Angular. |
|||
|
|||
Це досягає чогось подібного до того, що можна зробити з Flask-apispec. |
|||
|
|||
Він має інтегровану систему впровадження залежностей, натхненну Angular two. Він потребує попередньої реєстрації «injectables» (як і всі інші системи впровадження залежностей, які я знаю), тому це збільшує багатослівність та повторення коду. |
|||
|
|||
Оскільки параметри описані за допомогою типів TypeScript (подібно до підказок типу Python), підтримка редактора досить хороша. |
|||
|
|||
Але оскільки дані TypeScript не зберігаються після компіляції в JavaScript, вони не можуть покладатися на типи для визначення перевірки, серіалізації та документації одночасно. Через це та деякі дизайнерські рішення, щоб отримати перевірку, серіалізацію та автоматичну генерацію схеми, потрібно додати декоратори в багатьох місцях. Таким чином код стає досить багатослівним. |
|||
|
|||
Він не дуже добре обробляє вкладені моделі. Отже, якщо тіло JSON у запиті є об’єктом JSON із внутрішніми полями, які, у свою чергу, є вкладеними об’єктами JSON, його неможливо належним чином задокументувати та перевірити. |
|||
|
|||
!!! Перегляньте "Надихнуло **FastAPI** на" |
|||
Використовувати типи Python, щоб мати чудову підтримку редактора. |
|||
|
|||
Мати потужну систему впровадження залежностей. Знайдіть спосіб звести до мінімуму повторення коду. |
|||
|
|||
### <a href="https://sanic.readthedocs.io/en/latest/" class="external-link" target="_blank">Sanic</a> |
|||
|
|||
Це був один із перших надзвичайно швидких фреймворків Python на основі `asyncio`. Він був дуже схожий на Flask. |
|||
|
|||
!!! Примітка "Технічні деталі" |
|||
Він використовував <a href="https://github.com/MagicStack/uvloop" class="external-link" target="_blank">`uvloop`</a> замість стандартного циклу Python `asyncio`. Ось що зробило його таким швидким. |
|||
|
|||
Це явно надихнуло Uvicorn і Starlette, які зараз швидші за Sanic у відкритих тестах. |
|||
|
|||
!!! Перегляньте "Надихнуло **FastAPI** на" |
|||
Знайти спосіб отримати божевільну продуктивність. |
|||
|
|||
Ось чому **FastAPI** базується на Starlette, оскільки це найшвидша доступна структура (перевірена тестами сторонніх розробників). |
|||
|
|||
### <a href="https://falconframework.org/" class="external-link" target="_blank">Falcon</a> |
|||
|
|||
Falcon — ще один високопродуктивний фреймворк Python, він розроблений як мінімальний і працює як основа інших фреймворків, таких як Hug. |
|||
|
|||
Він розроблений таким чином, щоб мати функції, які отримують два параметри, один «запит» і один «відповідь». Потім ви «читаєте» частини запиту та «записуєте» частини у відповідь. Через такий дизайн неможливо оголосити параметри запиту та тіла за допомогою стандартних підказок типу Python як параметри функції. |
|||
|
|||
Таким чином, перевірка даних, серіалізація та документація повинні виконуватися в коді, а не автоматично. Або вони повинні бути реалізовані як фреймворк поверх Falcon, як Hug. Така сама відмінність спостерігається в інших фреймворках, натхненних дизайном Falcon, що мають один об’єкт запиту та один об’єкт відповіді як параметри. |
|||
|
|||
!!! Перегляньте "Надихнуло **FastAPI** на" |
|||
Знайти способи отримати чудову продуктивність. |
|||
|
|||
Разом із Hug (оскільки Hug базується на Falcon) надихнув **FastAPI** оголосити параметр `response` у функціях. |
|||
|
|||
Хоча у FastAPI це необов’язково, і використовується в основному для встановлення заголовків, файлів cookie та альтернативних кодів стану. |
|||
|
|||
### <a href="https://moltenframework.com/" class="external-link" target="_blank">Molten</a> |
|||
|
|||
Я відкрив для себе Molten на перших етапах створення **FastAPI**. І він має досить схожі ідеї: |
|||
|
|||
* Базується на підказках типу Python. |
|||
* Перевірка та документація цих типів. |
|||
* Система впровадження залежностей. |
|||
|
|||
Він не використовує перевірку даних, серіалізацію та бібліотеку документації сторонніх розробників, як Pydantic, він має свою власну. Таким чином, ці визначення типів даних не можна було б використовувати повторно так легко. |
|||
|
|||
Це вимагає трохи більш докладних конфігурацій. І оскільки він заснований на WSGI (замість ASGI), він не призначений для використання високопродуктивних інструментів, таких як Uvicorn, Starlette і Sanic. |
|||
|
|||
Система впровадження залежностей вимагає попередньої реєстрації залежностей, і залежності вирішуються на основі оголошених типів. Отже, неможливо оголосити більше ніж один «компонент», який надає певний тип. |
|||
|
|||
Маршрути оголошуються в одному місці з використанням функцій, оголошених в інших місцях (замість використання декораторів, які можна розмістити безпосередньо поверх функції, яка обробляє кінцеву точку). Це ближче до того, як це робить Django, ніж до Flask (і Starlette). Він розділяє в коді речі, які відносно тісно пов’язані. |
|||
|
|||
!!! Перегляньте "Надихнуло **FastAPI** на" |
|||
Визначити додаткові перевірки для типів даних, використовуючи значення "за замовчуванням" атрибутів моделі. Це покращує підтримку редактора, а раніше вона була недоступна в Pydantic. |
|||
|
|||
Це фактично надихнуло оновити частини Pydantic, щоб підтримувати той самий стиль оголошення перевірки (всі ці функції вже доступні в Pydantic). |
|||
|
|||
### <a href="https://www.hug.rest/" class="external-link" target="_blank">Hug</a> |
|||
|
|||
Hug був одним із перших фреймворків, який реалізував оголошення типів параметрів API за допомогою підказок типу Python. Це була чудова ідея, яка надихнула інші інструменти зробити те саме. |
|||
|
|||
Він використовував спеціальні типи у своїх оголошеннях замість стандартних типів Python, але це все одно був величезний крок вперед. |
|||
|
|||
Це також був один із перших фреймворків, який генерував спеціальну схему, що оголошувала весь API у JSON. |
|||
|
|||
Він не базувався на таких стандартах, як OpenAPI та JSON Schema. Тому було б непросто інтегрувати його з іншими інструментами, як-от Swagger UI. Але знову ж таки, це була дуже інноваційна ідея. |
|||
|
|||
Він має цікаву незвичайну функцію: використовуючи ту саму структуру, можна створювати API, а також CLI. |
|||
|
|||
Оскільки він заснований на попередньому стандарті для синхронних веб-фреймворків Python (WSGI), він не може працювати з Websockets та іншими речами, хоча він також має високу продуктивність. |
|||
|
|||
!!! Інформація |
|||
Hug створив Тімоті Крослі, той самий творець <a href="https://github.com/timothycrosley/isort" class="external-link" target="_blank">`isort`</a>, чудовий інструмент для автоматичного сортування імпорту у файлах Python. |
|||
|
|||
!!! Перегляньте "Надихнуло **FastAPI** на" |
|||
Hug надихнув частину APIStar і був одним із найбільш перспективних інструментів, поряд із APIStar. |
|||
|
|||
Hug надихнув **FastAPI** на використання підказок типу Python для оголошення параметрів і автоматичного створення схеми, що визначає API. |
|||
|
|||
Hug надихнув **FastAPI** оголосити параметр `response` у функціях для встановлення заголовків і файлів cookie. |
|||
|
|||
### <a href="https://github.com/encode/apistar" class="external-link" target="_blank">APIStar</a> (<= 0,5) |
|||
|
|||
Безпосередньо перед тим, як вирішити створити **FastAPI**, я знайшов сервер **APIStar**. Він мав майже все, що я шукав, і мав чудовий дизайн. |
|||
|
|||
Це була одна з перших реалізацій фреймворку, що використовує підказки типу Python для оголошення параметрів і запитів, яку я коли-небудь бачив (до NestJS і Molten). Я знайшов його більш-менш одночасно з Hug. Але APIStar використовував стандарт OpenAPI. |
|||
|
|||
Він мав автоматичну перевірку даних, серіалізацію даних і генерацію схеми OpenAPI на основі підказок того самого типу в кількох місцях. |
|||
|
|||
Визначення схеми тіла не використовували ті самі підказки типу Python, як Pydantic, воно було трохи схоже на Marshmallow, тому підтримка редактора була б не такою хорошою, але все ж APIStar був найкращим доступним варіантом. |
|||
|
|||
Він мав найкращі показники продуктивності на той час (перевершив лише Starlette). |
|||
|
|||
Спочатку він не мав автоматичного веб-інтерфейсу документації API, але я знав, що можу додати до нього інтерфейс користувача Swagger. |
|||
|
|||
Він мав систему введення залежностей. Він вимагав попередньої реєстрації компонентів, як і інші інструменти, розглянуті вище. Але все одно це була чудова функція. |
|||
|
|||
Я ніколи не міг використовувати його в повноцінному проекті, оскільки він не мав інтеграції безпеки, тому я не міг замінити всі функції, які мав, генераторами повного стеку на основі Flask-apispec. У моїх невиконаних проектах я мав створити запит на вилучення, додавши цю функцію. |
|||
|
|||
Але потім фокус проекту змінився. |
|||
|
|||
Це вже не був веб-фреймворк API, оскільки творцю потрібно було зосередитися на Starlette. |
|||
|
|||
Тепер APIStar — це набір інструментів для перевірки специфікацій OpenAPI, а не веб-фреймворк. |
|||
|
|||
!!! Інформація |
|||
APIStar створив Том Крісті. Той самий хлопець, який створив: |
|||
|
|||
* Django REST Framework |
|||
* Starlette (на якому базується **FastAPI**) |
|||
* Uvicorn (використовується Starlette і **FastAPI**) |
|||
|
|||
!!! Перегляньте "Надихнуло **FastAPI** на" |
|||
Існувати. |
|||
|
|||
Ідею оголошення кількох речей (перевірки даних, серіалізації та документації) за допомогою тих самих типів Python, які в той же час забезпечували чудову підтримку редактора, я вважав геніальною ідеєю. |
|||
|
|||
І після тривалого пошуку подібної структури та тестування багатьох різних альтернатив, APIStar став найкращим доступним варіантом. |
|||
|
|||
Потім APIStar перестав існувати як сервер, і було створено Starlette, який став новою кращою основою для такої системи. Це стало останнім джерелом натхнення для створення **FastAPI**. Я вважаю **FastAPI** «духовним спадкоємцем» APIStar, удосконалюючи та розширюючи функції, систему введення тексту та інші частини на основі досвіду, отриманого від усіх цих попередніх інструментів. |
|||
|
|||
## Використовується **FastAPI** |
|||
|
|||
### <a href="https://pydantic-docs.helpmanual.io/" class="external-link" target="_blank">Pydantic</a> |
|||
|
|||
Pydantic — це бібліотека для визначення перевірки даних, серіалізації та документації (за допомогою схеми JSON) на основі підказок типу Python. |
|||
|
|||
Це робить його надзвичайно інтуїтивним. |
|||
|
|||
Його можна порівняти з Marshmallow. Хоча він швидший за Marshmallow у тестах. Оскільки він базується на тих самих підказках типу Python, підтримка редактора чудова. |
|||
|
|||
!!! Перегляньте "**FastAPI** використовує його для" |
|||
Виконання перевірки всіх даних, серіалізації даних і автоматичної документацію моделі (на основі схеми JSON). |
|||
|
|||
Потім **FastAPI** бере ці дані схеми JSON і розміщує їх у OpenAPI, окремо від усіх інших речей, які він робить. |
|||
|
|||
### <a href="https://www.starlette.io/" class="external-link" target="_blank">Starlette</a> |
|||
|
|||
Starlette — це легкий фреймворк/набір інструментів <abbr title="The new standard for build asynchronous Python web">ASGI</abbr>, який ідеально підходить для створення високопродуктивних asyncio сервісів. |
|||
|
|||
Він дуже простий та інтуїтивно зрозумілий. Його розроблено таким чином, щоб його можна було легко розширювати та мати модульні компоненти. |
|||
|
|||
Він має: |
|||
|
|||
* Серйозно вражаючу продуктивність. |
|||
* Підтримку WebSocket. |
|||
* Фонові завдання в процесі. |
|||
* Події запуску та завершення роботи. |
|||
* Тестового клієнта, побудований на HTTPX. |
|||
* CORS, GZip, статичні файли, потокові відповіді. |
|||
* Підтримку сеансів і файлів cookie. |
|||
* 100% покриття тестом. |
|||
* 100% анотовану кодову базу. |
|||
* Кілька жорстких залежностей. |
|||
|
|||
Starlette наразі є найшвидшим фреймворком Python із перевірених. Перевершує лише Uvicorn, який є не фреймворком, а сервером. |
|||
|
|||
Starlette надає всі основні функції веб-мікрофреймворку. |
|||
|
|||
Але він не забезпечує автоматичної перевірки даних, серіалізації чи документації. |
|||
|
|||
Це одна з головних речей, які **FastAPI** додає зверху, все на основі підказок типу Python (з використанням Pydantic). Це, а також система впровадження залежностей, утиліти безпеки, створення схеми OpenAPI тощо. |
|||
|
|||
!!! Примітка "Технічні деталі" |
|||
ASGI — це новий «стандарт», який розробляється членами основної команди Django. Це ще не «стандарт Python» (PEP), хоча вони в процесі цього. |
|||
|
|||
Тим не менш, він уже використовується як «стандарт» кількома інструментами. Це значно покращує сумісність, оскільки ви можете переключити Uvicorn на будь-який інший сервер ASGI (наприклад, Daphne або Hypercorn), або ви можете додати інструменти, сумісні з ASGI, як-от `python-socketio`. |
|||
|
|||
!!! Перегляньте "**FastAPI** використовує його для" |
|||
Керування всіма основними веб-частинами. Додавання функцій зверху. |
|||
|
|||
Сам клас `FastAPI` безпосередньо успадковує клас `Starlette`. |
|||
|
|||
Отже, усе, що ви можете робити зі Starlette, ви можете робити це безпосередньо за допомогою **FastAPI**, оскільки це, по суті, Starlette на стероїдах. |
|||
|
|||
### <a href="https://www.uvicorn.org/" class="external-link" target="_blank">Uvicorn</a> |
|||
|
|||
Uvicorn — це блискавичний сервер ASGI, побудований на uvloop і httptools. |
|||
|
|||
Це не веб-фреймворк, а сервер. Наприклад, він не надає інструментів для маршрутизації. Це те, що фреймворк на кшталт Starlette (або **FastAPI**) забезпечить поверх нього. |
|||
|
|||
Це рекомендований сервер для Starlette і **FastAPI**. |
|||
|
|||
!!! Перегляньте "**FastAPI** рекомендує це як" |
|||
Основний веб-сервер для запуску програм **FastAPI**. |
|||
|
|||
Ви можете поєднати його з Gunicorn, щоб мати асинхронний багатопроцесний сервер. |
|||
|
|||
Додаткову інформацію див. у розділі [Розгортання](deployment/index.md){.internal-link target=_blank}. |
|||
|
|||
## Орієнтири та швидкість |
|||
|
|||
Щоб зрозуміти, порівняти та побачити різницю між Uvicorn, Starlette і FastAPI, перегляньте розділ про [Бенчмарки](benchmarks.md){.internal-link target=_blank}. |
|||
@ -0,0 +1,448 @@ |
|||
# Вступ до типів Python |
|||
|
|||
Python підтримує додаткові "підказки типу" ("type hints") (також звані "анотаціями типу" ("type annotations")). |
|||
|
|||
Ці **"type hints"** є спеціальним синтаксисом, що дозволяє оголошувати <abbr title="наприклад: str, int, float, bool">тип</abbr> змінної. |
|||
|
|||
За допомогою оголошення типів для ваших змінних, редактори та інструменти можуть надати вам кращу підтримку. |
|||
|
|||
Це просто **швидкий посібник / нагадування** про анотації типів у Python. Він покриває лише мінімум, необхідний щоб використовувати їх з **FastAPI**... що насправді дуже мало. |
|||
|
|||
**FastAPI** повністю базується на цих анотаціях типів, вони дають йому багато переваг. |
|||
|
|||
Але навіть якщо ви ніколи не використаєте **FastAPI**, вам буде корисно дізнатись трохи про них. |
|||
|
|||
!!! note |
|||
Якщо ви експерт у Python і ви вже знаєте усе про анотації типів - перейдіть до наступного розділу. |
|||
|
|||
## Мотивація |
|||
|
|||
Давайте почнемо з простого прикладу: |
|||
|
|||
```Python |
|||
{!../../../docs_src/python_types/tutorial001.py!} |
|||
``` |
|||
|
|||
Виклик цієї програми виводить: |
|||
|
|||
``` |
|||
John Doe |
|||
``` |
|||
|
|||
Функція виконує наступне: |
|||
|
|||
* Бере `first_name` та `last_name`. |
|||
* Конвертує кожну літеру кожного слова у верхній регістр за допомогою `title()`. |
|||
* <abbr title="З’єднує їх, як одне ціле. З вмістом один за одним.">Конкатенує</abbr> їх разом із пробілом по середині. |
|||
|
|||
```Python hl_lines="2" |
|||
{!../../../docs_src/python_types/tutorial001.py!} |
|||
``` |
|||
|
|||
### Редагуйте це |
|||
|
|||
Це дуже проста програма. |
|||
|
|||
Але тепер уявіть, що ви писали це з нуля. |
|||
|
|||
У певний момент ви розпочали б визначення функції, у вас були б готові параметри... |
|||
|
|||
Але тоді вам потрібно викликати "той метод, який переводить першу літеру у верхній регістр". |
|||
|
|||
Це буде `upper`? Чи `uppercase`? `first_uppercase`? `capitalize`? |
|||
|
|||
Тоді ви спробуєте давнього друга програміста - автозаповнення редактора коду. |
|||
|
|||
Ви надрукуєте перший параметр функції, `first_name`, тоді крапку (`.`), а тоді натиснете `Ctrl+Space`, щоб запустити автозаповнення. |
|||
|
|||
Але, на жаль, ви не отримаєте нічого корисного: |
|||
|
|||
<img src="/img/python-types/image01.png"> |
|||
|
|||
### Додайте типи |
|||
|
|||
Давайте змінимо один рядок з попередньої версії. |
|||
|
|||
Ми змінимо саме цей фрагмент, параметри функції, з: |
|||
|
|||
```Python |
|||
first_name, last_name |
|||
``` |
|||
|
|||
на: |
|||
|
|||
```Python |
|||
first_name: str, last_name: str |
|||
``` |
|||
|
|||
Ось і все. |
|||
|
|||
Це "type hints": |
|||
|
|||
```Python hl_lines="1" |
|||
{!../../../docs_src/python_types/tutorial002.py!} |
|||
``` |
|||
|
|||
Це не те саме, що оголошення значень за замовчуванням, як це було б з: |
|||
|
|||
```Python |
|||
first_name="john", last_name="doe" |
|||
``` |
|||
|
|||
Це зовсім інше. |
|||
|
|||
Ми використовуємо двокрапку (`:`), не дорівнює (`=`). |
|||
|
|||
І додавання анотації типу зазвичай не змінює того, що сталось би без них. |
|||
|
|||
Але тепер, уявіть що ви посеред процесу створення функції, але з анотаціями типів. |
|||
|
|||
В цей же момент, ви спробуєте викликати автозаповнення з допомогою `Ctrl+Space` і побачите: |
|||
|
|||
<img src="/img/python-types/image02.png"> |
|||
|
|||
Разом з цим, ви можете прокручувати, переглядати опції, допоки ви не знайдете одну, що звучить схоже: |
|||
|
|||
<img src="/img/python-types/image03.png"> |
|||
|
|||
## Більше мотивації |
|||
|
|||
Перевірте цю функцію, вона вже має анотацію типу: |
|||
|
|||
```Python hl_lines="1" |
|||
{!../../../docs_src/python_types/tutorial003.py!} |
|||
``` |
|||
|
|||
Оскільки редактор знає типи змінних, ви не тільки отримаєте автозаповнення, ви також отримаєте перевірку помилок: |
|||
|
|||
<img src="/img/python-types/image04.png"> |
|||
|
|||
Тепер ви знаєте, щоб виправити це, вам потрібно перетворити `age` у строку з допомогою `str(age)`: |
|||
|
|||
```Python hl_lines="2" |
|||
{!../../../docs_src/python_types/tutorial004.py!} |
|||
``` |
|||
|
|||
## Оголошення типів |
|||
|
|||
Щойно ви побачили основне місце для оголошення анотацій типу. Як параметри функції. |
|||
|
|||
Це також основне місце, де ви б їх використовували у **FastAPI**. |
|||
|
|||
### Прості типи |
|||
|
|||
Ви можете оголошувати усі стандартні типи у Python, не тільки `str`. |
|||
|
|||
Ви можете використовувати, наприклад: |
|||
|
|||
* `int` |
|||
* `float` |
|||
* `bool` |
|||
* `bytes` |
|||
|
|||
```Python hl_lines="1" |
|||
{!../../../docs_src/python_types/tutorial005.py!} |
|||
``` |
|||
|
|||
### Generic-типи з параметрами типів |
|||
|
|||
Існують деякі структури даних, які можуть містити інші значення, наприклад `dict`, `list`, `set` та `tuple`. І внутрішні значення також можуть мати свій тип. |
|||
|
|||
Ці типи, які мають внутрішні типи, називаються "**generic**" типами. І оголосити їх можна навіть із внутрішніми типами. |
|||
|
|||
Щоб оголосити ці типи та внутрішні типи, ви можете використовувати стандартний модуль Python `typing`. Він існує спеціально для підтримки анотацій типів. |
|||
|
|||
#### Новіші версії Python |
|||
|
|||
Синтаксис із використанням `typing` **сумісний** з усіма версіями, від Python 3.6 до останніх, включаючи Python 3.9, Python 3.10 тощо. |
|||
|
|||
У міру розвитку Python **новіші версії** мають покращену підтримку анотацій типів і в багатьох випадках вам навіть не потрібно буде імпортувати та використовувати модуль `typing` для оголошення анотацій типу. |
|||
|
|||
Якщо ви можете вибрати новішу версію Python для свого проекту, ви зможете скористатися цією додатковою простотою. Дивіться кілька прикладів нижче. |
|||
|
|||
#### List (список) |
|||
|
|||
Наприклад, давайте визначимо змінну, яка буде `list` із `str`. |
|||
|
|||
=== "Python 3.6 і вище" |
|||
|
|||
З модуля `typing`, імпортуємо `List` (з великої літери `L`): |
|||
|
|||
``` Python hl_lines="1" |
|||
{!> ../../../docs_src/python_types/tutorial006.py!} |
|||
``` |
|||
|
|||
Оголосимо змінну з тим самим синтаксисом двокрапки (`:`). |
|||
|
|||
Як тип вкажемо `List`, який ви імпортували з `typing`. |
|||
|
|||
Оскільки список є типом, який містить деякі внутрішні типи, ви поміщаєте їх у квадратні дужки: |
|||
|
|||
```Python hl_lines="4" |
|||
{!> ../../../docs_src/python_types/tutorial006.py!} |
|||
``` |
|||
|
|||
=== "Python 3.9 і вище" |
|||
|
|||
Оголосимо змінну з тим самим синтаксисом двокрапки (`:`). |
|||
|
|||
Як тип вкажемо `list`. |
|||
|
|||
Оскільки список є типом, який містить деякі внутрішні типи, ви поміщаєте їх у квадратні дужки: |
|||
|
|||
```Python hl_lines="1" |
|||
{!> ../../../docs_src/python_types/tutorial006_py39.py!} |
|||
``` |
|||
|
|||
!!! info |
|||
Ці внутрішні типи в квадратних дужках називаються "параметрами типу". |
|||
|
|||
У цьому випадку, `str` це параметр типу переданий у `List` (або `list` у Python 3.9 і вище). |
|||
|
|||
Це означає: "змінна `items` це `list`, і кожен з елементів у цьому списку - `str`". |
|||
|
|||
!!! tip |
|||
Якщо ви використовуєте Python 3.9 і вище, вам не потрібно імпортувати `List` з `typing`, ви можете використовувати натомість тип `list`. |
|||
|
|||
Зробивши це, ваш редактор може надати підтримку навіть під час обробки елементів зі списку: |
|||
|
|||
<img src="/img/python-types/image05.png"> |
|||
|
|||
Без типів цього майже неможливо досягти. |
|||
|
|||
Зверніть увагу, що змінна `item` є одним із елементів у списку `items`. |
|||
|
|||
І все ж редактор знає, що це `str`, і надає підтримку для цього. |
|||
|
|||
#### Tuple and Set (кортеж та набір) |
|||
|
|||
Ви повинні зробити те ж саме, щоб оголосити `tuple` і `set`: |
|||
|
|||
=== "Python 3.6 і вище" |
|||
|
|||
```Python hl_lines="1 4" |
|||
{!> ../../../docs_src/python_types/tutorial007.py!} |
|||
``` |
|||
|
|||
=== "Python 3.9 і вище" |
|||
|
|||
```Python hl_lines="1" |
|||
{!> ../../../docs_src/python_types/tutorial007_py39.py!} |
|||
``` |
|||
|
|||
Це означає: |
|||
|
|||
* Змінна `items_t` це `tuple` з 3 елементами, `int`, ще `int`, та `str`. |
|||
* Змінна `items_s` це `set`, і кожен його елемент типу `bytes`. |
|||
|
|||
#### Dict (словник) |
|||
|
|||
Щоб оголосити `dict`, вам потрібно передати 2 параметри типу, розділені комами. |
|||
|
|||
Перший параметр типу для ключа у `dict`. |
|||
|
|||
Другий параметр типу для значення у `dict`: |
|||
|
|||
=== "Python 3.6 і вище" |
|||
|
|||
```Python hl_lines="1 4" |
|||
{!> ../../../docs_src/python_types/tutorial008.py!} |
|||
``` |
|||
|
|||
=== "Python 3.9 і вище" |
|||
|
|||
```Python hl_lines="1" |
|||
{!> ../../../docs_src/python_types/tutorial008_py39.py!} |
|||
``` |
|||
|
|||
Це означає: |
|||
|
|||
* Змінна `prices` це `dict`: |
|||
* Ключі цього `dict` типу `str` (наприклад, назва кожного елементу). |
|||
* Значення цього `dict` типу `float` (наприклад, ціна кожного елементу). |
|||
|
|||
#### Union (об'єднання) |
|||
|
|||
Ви можете оголосити, що змінна може бути будь-яким із **кількох типів**, наприклад, `int` або `str`. |
|||
|
|||
У Python 3.6 і вище (включаючи Python 3.10) ви можете використовувати тип `Union` з `typing` і вставляти в квадратні дужки можливі типи, які можна прийняти. |
|||
|
|||
У Python 3.10 також є **альтернативний синтаксис**, у якому ви можете розділити можливі типи за допомогою <abbr title='також називають «побітовим "або" оператором», але це значення тут не актуальне'>вертикальної смуги (`|`)</abbr>. |
|||
|
|||
=== "Python 3.6 і вище" |
|||
|
|||
```Python hl_lines="1 4" |
|||
{!> ../../../docs_src/python_types/tutorial008b.py!} |
|||
``` |
|||
|
|||
=== "Python 3.10 і вище" |
|||
|
|||
```Python hl_lines="1" |
|||
{!> ../../../docs_src/python_types/tutorial008b_py310.py!} |
|||
``` |
|||
|
|||
В обох випадках це означає, що `item` може бути `int` або `str`. |
|||
|
|||
#### Possibly `None` (Optional) |
|||
|
|||
Ви можете оголосити, що значення може мати тип, наприклад `str`, але також може бути `None`. |
|||
|
|||
У Python 3.6 і вище (включаючи Python 3.10) ви можете оголосити його, імпортувавши та використовуючи `Optional` з модуля `typing`. |
|||
|
|||
```Python hl_lines="1 4" |
|||
{!../../../docs_src/python_types/tutorial009.py!} |
|||
``` |
|||
|
|||
Використання `Optional[str]` замість просто `str` дозволить редактору допомогти вам виявити помилки, коли ви могли б вважати, що значенням завжди є `str`, хоча насправді воно також може бути `None`. |
|||
|
|||
`Optional[Something]` насправді є скороченням для `Union[Something, None]`, вони еквівалентні. |
|||
|
|||
Це також означає, що в Python 3.10 ви можете використовувати `Something | None`: |
|||
|
|||
=== "Python 3.6 і вище" |
|||
|
|||
```Python hl_lines="1 4" |
|||
{!> ../../../docs_src/python_types/tutorial009.py!} |
|||
``` |
|||
|
|||
=== "Python 3.6 і вище - альтернатива" |
|||
|
|||
```Python hl_lines="1 4" |
|||
{!> ../../../docs_src/python_types/tutorial009b.py!} |
|||
``` |
|||
|
|||
=== "Python 3.10 і вище" |
|||
|
|||
```Python hl_lines="1" |
|||
{!> ../../../docs_src/python_types/tutorial009_py310.py!} |
|||
``` |
|||
|
|||
#### Generic типи |
|||
|
|||
Ці типи, які приймають параметри типу у квадратних дужках, називаються **Generic types** or **Generics**, наприклад: |
|||
|
|||
=== "Python 3.6 і вище" |
|||
|
|||
* `List` |
|||
* `Tuple` |
|||
* `Set` |
|||
* `Dict` |
|||
* `Union` |
|||
* `Optional` |
|||
* ...та інші. |
|||
|
|||
=== "Python 3.9 і вище" |
|||
|
|||
Ви можете використовувати ті самі вбудовані типи, як generic (з квадратними дужками та типами всередині): |
|||
|
|||
* `list` |
|||
* `tuple` |
|||
* `set` |
|||
* `dict` |
|||
|
|||
І те саме, що й у Python 3.6, із модуля `typing`: |
|||
|
|||
* `Union` |
|||
* `Optional` |
|||
* ...та інші. |
|||
|
|||
=== "Python 3.10 і вище" |
|||
|
|||
Ви можете використовувати ті самі вбудовані типи, як generic (з квадратними дужками та типами всередині): |
|||
|
|||
* `list` |
|||
* `tuple` |
|||
* `set` |
|||
* `dict` |
|||
|
|||
І те саме, що й у Python 3.6, із модуля `typing`: |
|||
|
|||
* `Union` |
|||
* `Optional` (так само як у Python 3.6) |
|||
* ...та інші. |
|||
|
|||
У Python 3.10, як альтернатива використанню `Union` та `Optional`, ви можете використовувати <abbr title='також називають «побітовим "або" оператором», але це значення тут не актуальне'>вертикальну смугу (`|`)</abbr> щоб оголосити об'єднання типів. |
|||
|
|||
### Класи як типи |
|||
|
|||
Ви також можете оголосити клас як тип змінної. |
|||
|
|||
Скажімо, у вас є клас `Person` з імʼям: |
|||
|
|||
```Python hl_lines="1-3" |
|||
{!../../../docs_src/python_types/tutorial010.py!} |
|||
``` |
|||
|
|||
Потім ви можете оголосити змінну типу `Person`: |
|||
|
|||
```Python hl_lines="6" |
|||
{!../../../docs_src/python_types/tutorial010.py!} |
|||
``` |
|||
|
|||
І знову ж таки, ви отримуєте всю підтримку редактора: |
|||
|
|||
<img src="/img/python-types/image06.png"> |
|||
|
|||
## Pydantic моделі |
|||
|
|||
<a href="https://pydantic-docs.helpmanual.io/" class="external-link" target="_blank">Pydantic</a> це бібліотека Python для валідації даних. |
|||
|
|||
Ви оголошуєте «форму» даних як класи з атрибутами. |
|||
|
|||
І кожен атрибут має тип. |
|||
|
|||
Потім ви створюєте екземпляр цього класу з деякими значеннями, і він перевірить ці значення, перетворить їх у відповідний тип (якщо є потреба) і надасть вам об’єкт з усіма даними. |
|||
|
|||
І ви отримуєте всю підтримку редактора з цим отриманим об’єктом. |
|||
|
|||
Приклад з документації Pydantic: |
|||
|
|||
=== "Python 3.6 і вище" |
|||
|
|||
```Python |
|||
{!> ../../../docs_src/python_types/tutorial011.py!} |
|||
``` |
|||
|
|||
=== "Python 3.9 і вище" |
|||
|
|||
```Python |
|||
{!> ../../../docs_src/python_types/tutorial011_py39.py!} |
|||
``` |
|||
|
|||
=== "Python 3.10 і вище" |
|||
|
|||
```Python |
|||
{!> ../../../docs_src/python_types/tutorial011_py310.py!} |
|||
``` |
|||
|
|||
!!! info |
|||
Щоб дізнатись більше про <a href="https://pydantic-docs.helpmanual.io/" class="external-link" target="_blank">Pydantic, перегляньте його документацію</a>. |
|||
|
|||
**FastAPI** повністю базується на Pydantic. |
|||
|
|||
Ви побачите набагато більше цього всього на практиці в [Tutorial - User Guide](tutorial/index.md){.internal-link target=_blank}. |
|||
|
|||
## Анотації типів у **FastAPI** |
|||
|
|||
**FastAPI** використовує ці підказки для виконання кількох речей. |
|||
|
|||
З **FastAPI** ви оголошуєте параметри з підказками типу, і отримуєте: |
|||
|
|||
* **Підтримку редактора**. |
|||
* **Перевірку типів**. |
|||
|
|||
...і **FastAPI** використовує ті самі оголошення для: |
|||
|
|||
* **Визначення вимог**: з параметрів шляху запиту, параметрів запиту, заголовків, тіл, залежностей тощо. |
|||
* **Перетворення даних**: із запиту в необхідний тип. |
|||
* **Перевірка даних**: що надходять від кожного запиту: |
|||
* Генерування **автоматичних помилок**, що повертаються клієнту, коли дані недійсні. |
|||
* **Документування** API за допомогою OpenAPI: |
|||
* який потім використовується для автоматичної інтерактивної документації користувальницьких інтерфейсів. |
|||
|
|||
Все це може здатися абстрактним. Не хвилюйтеся. Ви побачите все це в дії в [Туторіал - Посібник користувача](tutorial/index.md){.internal-link target=_blank}. |
|||
|
|||
Важливо те, що за допомогою стандартних типів Python в одному місці (замість того, щоб додавати більше класів, декораторів тощо), **FastAPI** зробить багато роботи за вас. |
|||
|
|||
!!! info |
|||
Якщо ви вже пройшли весь навчальний посібник і повернулися, щоб дізнатися більше про типи, ось хороший ресурс <a href="https://mypy.readthedocs.io/en/latest/cheat_sheet_py3.html" class="external-link" target="_blank">"шпаргалка" від `mypy`</a>. |
|||
@ -0,0 +1,80 @@ |
|||
# Туторіал - Посібник користувача |
|||
|
|||
У цьому посібнику показано, як користуватися **FastAPI** з більшістю його функцій, крок за кроком. |
|||
|
|||
Кожен розділ поступово надбудовується на попередні, але він структурований на окремі теми, щоб ви могли перейти безпосередньо до будь-якої конкретної, щоб вирішити ваші конкретні потреби API. |
|||
|
|||
Він також створений як довідник для роботи у майбутньому. |
|||
|
|||
Тож ви можете повернутися і побачити саме те, що вам потрібно. |
|||
|
|||
## Запустіть код |
|||
|
|||
Усі блоки коду можна скопіювати та використовувати безпосередньо (це фактично перевірені файли Python). |
|||
|
|||
Щоб запустити будь-який із прикладів, скопіюйте код у файл `main.py` і запустіть `uvicorn` за допомогою: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ uvicorn main:app --reload |
|||
|
|||
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) |
|||
<span style="color: green;">INFO</span>: Started reloader process [28720] |
|||
<span style="color: green;">INFO</span>: Started server process [28722] |
|||
<span style="color: green;">INFO</span>: Waiting for application startup. |
|||
<span style="color: green;">INFO</span>: Application startup complete. |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
**ДУЖЕ радимо** написати або скопіювати код, відредагувати його та запустити локально. |
|||
|
|||
Використання його у своєму редакторі – це те, що дійсно показує вам переваги FastAPI, бачите, як мало коду вам потрібно написати, всі перевірки типів, автозаповнення тощо. |
|||
|
|||
--- |
|||
|
|||
## Встановлення FastAPI |
|||
|
|||
Першим кроком є встановлення FastAPI. |
|||
|
|||
Для туторіалу ви можете встановити його з усіма необов’язковими залежностями та функціями: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ pip install "fastapi[all]" |
|||
|
|||
---> 100% |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
...який також включає `uvicorn`, який ви можете використовувати як сервер, який запускає ваш код. |
|||
|
|||
!!! note |
|||
Ви також можете встановити його частина за частиною. |
|||
|
|||
Це те, що ви, ймовірно, зробили б, коли захочете розгорнути свою програму у виробничому середовищі: |
|||
|
|||
``` |
|||
pip install fastapi |
|||
``` |
|||
|
|||
Також встановіть `uvicorn`, щоб він працював як сервер: |
|||
|
|||
``` |
|||
pip install "uvicorn[standard]" |
|||
``` |
|||
|
|||
І те саме для кожної з опціональних залежностей, які ви хочете використовувати. |
|||
|
|||
## Розширений посібник користувача |
|||
|
|||
Існує також **Розширений посібник користувача**, який ви зможете прочитати пізніше після цього **Туторіал - Посібник користувача**. |
|||
|
|||
**Розширений посібник користувача** засновано на цьому, використовує ті самі концепції та навчає вас деяким додатковим функціям. |
|||
|
|||
Але вам слід спочатку прочитати **Туторіал - Посібник користувача** (те, що ви зараз читаєте). |
|||
|
|||
Він розроблений таким чином, що ви можете створити повну програму лише за допомогою **Туторіал - Посібник користувача**, а потім розширити її різними способами, залежно від ваших потреб, використовуючи деякі з додаткових ідей з **Розширеного посібника користувача** . |
|||
@ -0,0 +1,333 @@ |
|||
# Những bước đầu tiên |
|||
|
|||
Tệp tin FastAPI đơn giản nhất có thể trông như này: |
|||
|
|||
```Python |
|||
{!../../../docs_src/first_steps/tutorial001.py!} |
|||
``` |
|||
|
|||
Sao chép sang một tệp tin `main.py`. |
|||
|
|||
Chạy live server: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ uvicorn main:app --reload |
|||
|
|||
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) |
|||
<span style="color: green;">INFO</span>: Started reloader process [28720] |
|||
<span style="color: green;">INFO</span>: Started server process [28722] |
|||
<span style="color: green;">INFO</span>: Waiting for application startup. |
|||
<span style="color: green;">INFO</span>: Application startup complete. |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
!!! note |
|||
Câu lệnh `uvicorn main:app` được giải thích như sau: |
|||
|
|||
* `main`: tệp tin `main.py` (một Python "mô đun"). |
|||
* `app`: một object được tạo ra bên trong `main.py` với dòng `app = FastAPI()`. |
|||
* `--reload`: làm server khởi động lại sau mỗi lần thay đổi. Chỉ sử dụng trong môi trường phát triển. |
|||
|
|||
Trong output, có một dòng giống như: |
|||
|
|||
```hl_lines="4" |
|||
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) |
|||
``` |
|||
|
|||
Dòng đó cho thấy URL, nơi mà app của bạn đang được chạy, trong máy local của bạn. |
|||
|
|||
### Kiểm tra |
|||
|
|||
Mở trình duyệt của bạn tại <a href="http://127.0.0.1:8000" class="external-link" target="_blank">http://127.0.0.1:8000</a>. |
|||
|
|||
Bạn sẽ thấy một JSON response như: |
|||
|
|||
```JSON |
|||
{"message": "Hello World"} |
|||
``` |
|||
|
|||
### Tài liệu tương tác API |
|||
|
|||
Bây giờ tới <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>. |
|||
|
|||
Bạn sẽ thấy một tài liệu tương tác API (cung cấp bởi <a href="https://github.com/swagger-api/swagger-ui" class="external-link" target="_blank">Swagger UI</a>): |
|||
|
|||
 |
|||
|
|||
### Phiên bản thay thế của tài liệu API |
|||
|
|||
Và bây giờ tới <a href="http://127.0.0.1:8000/redoc" class="external-link" target="_blank">http://127.0.0.1:8000/redoc</a>. |
|||
|
|||
Bạn sẽ thấy một bản thay thế của tài liệu (cung cấp bởi <a href="https://github.com/Rebilly/ReDoc" class="external-link" target="_blank">ReDoc</a>): |
|||
|
|||
 |
|||
|
|||
### OpenAPI |
|||
|
|||
**FastAPI** sinh một "schema" với tất cả API của bạn sử dụng tiêu chuẩn **OpenAPI** cho định nghĩa các API. |
|||
|
|||
#### "Schema" |
|||
|
|||
Một "schema" là một định nghĩa hoặc mô tả thứ gì đó. Không phải code triển khai của nó, nhưng chỉ là một bản mô tả trừu tượng. |
|||
|
|||
#### API "schema" |
|||
|
|||
Trong trường hợp này, <a href="https://github.com/OAI/OpenAPI-Specification" class="external-link" target="_blank">OpenAPI</a> là một bản mô tả bắt buộc cơ chế định nghĩa API của bạn. |
|||
|
|||
Định nghĩa cấu trúc này bao gồm những đường dẫn API của bạn, các tham số có thể có,... |
|||
|
|||
#### "Cấu trúc" dữ liệu |
|||
|
|||
Thuật ngữ "cấu trúc" (schema) cũng có thể được coi như là hình dạng của dữ liệu, tương tự như một JSON content. |
|||
|
|||
Trong trường hợp đó, nó có nghĩa là các thuộc tính JSON và các kiểu dữ liệu họ có,... |
|||
|
|||
#### OpenAPI và JSON Schema |
|||
|
|||
OpenAPI định nghĩa một cấu trúc API cho API của bạn. Và cấu trúc đó bao gồm các dịnh nghĩa (or "schema") về dữ liệu được gửi đi và nhận về bởi API của bạn, sử dụng **JSON Schema**, một tiêu chuẩn cho cấu trúc dữ liệu JSON. |
|||
|
|||
#### Kiểm tra `openapi.json` |
|||
|
|||
Nếu bạn tò mò về việc cấu trúc OpenAPI nhìn như thế nào thì FastAPI tự động sinh một JSON (schema) với các mô tả cho tất cả API của bạn. |
|||
|
|||
Bạn có thể thấy nó trực tiếp tại: <a href="http://127.0.0.1:8000/openapi.json" class="external-link" target="_blank">http://127.0.0.1:8000/openapi.json</a>. |
|||
|
|||
Nó sẽ cho thấy một JSON bắt đầu giống như: |
|||
|
|||
```JSON |
|||
{ |
|||
"openapi": "3.1.0", |
|||
"info": { |
|||
"title": "FastAPI", |
|||
"version": "0.1.0" |
|||
}, |
|||
"paths": { |
|||
"/items/": { |
|||
"get": { |
|||
"responses": { |
|||
"200": { |
|||
"description": "Successful Response", |
|||
"content": { |
|||
"application/json": { |
|||
|
|||
|
|||
|
|||
... |
|||
``` |
|||
|
|||
#### OpenAPI dùng để làm gì? |
|||
|
|||
Cấu trúc OpenAPI là sức mạnh của tài liệu tương tác. |
|||
|
|||
Và có hàng tá các bản thay thế, tất cả đều dựa trên OpenAPI. Bạn có thể dễ dàng thêm bất kì bản thay thế bào cho ứng dụng của bạn được xây dựng với **FastAPI**. |
|||
|
|||
Bạn cũng có thể sử dụng nó để sinh code tự động, với các client giao viết qua API của bạn. Ví dụ, frontend, mobile hoặc các ứng dụng IoT. |
|||
|
|||
## Tóm lại, từng bước một |
|||
|
|||
### Bước 1: import `FastAPI` |
|||
|
|||
```Python hl_lines="1" |
|||
{!../../../docs_src/first_steps/tutorial001.py!} |
|||
``` |
|||
|
|||
`FastAPI` là một Python class cung cấp tất cả chức năng cho API của bạn. |
|||
|
|||
!!! note "Chi tiết kĩ thuật" |
|||
`FastAPI` là một class kế thừa trực tiếp `Starlette`. |
|||
|
|||
Bạn cũng có thể sử dụng tất cả <a href="https://www.starlette.io/" class="external-link" target="_blank">Starlette</a> chức năng với `FastAPI`. |
|||
|
|||
### Bước 2: Tạo một `FastAPI` "instance" |
|||
|
|||
```Python hl_lines="3" |
|||
{!../../../docs_src/first_steps/tutorial001.py!} |
|||
``` |
|||
|
|||
Biến `app` này là một "instance" của class `FastAPI`. |
|||
|
|||
Đây sẽ là điểm cốt lõi để tạo ra tất cả API của bạn. |
|||
|
|||
`app` này chính là điều được nhắc tới bởi `uvicorn` trong câu lệnh: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ uvicorn main:app --reload |
|||
|
|||
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
Nếu bạn tạo ứng dụng của bạn giống như: |
|||
|
|||
```Python hl_lines="3" |
|||
{!../../../docs_src/first_steps/tutorial002.py!} |
|||
``` |
|||
|
|||
Và đặt nó trong một tệp tin `main.py`, sau đó bạn sẽ gọi `uvicorn` giống như: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ uvicorn main:my_awesome_api --reload |
|||
|
|||
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
### Bước 3: tạo một *đường dẫn toán tử* |
|||
|
|||
#### Đường dẫn |
|||
|
|||
"Đường dẫn" ở đây được nhắc tới là phần cuối cùng của URL bắt đầu từ `/`. |
|||
|
|||
Do đó, trong một URL nhìn giống như: |
|||
|
|||
``` |
|||
https://example.com/items/foo |
|||
``` |
|||
|
|||
...đường dẫn sẽ là: |
|||
|
|||
``` |
|||
/items/foo |
|||
``` |
|||
|
|||
!!! info |
|||
Một đường dẫn cũng là một cách gọi chung cho một "endpoint" hoặc một "route". |
|||
|
|||
Trong khi xây dựng một API, "đường dẫn" là các chính để phân tách "mối quan hệ" và "tài nguyên". |
|||
|
|||
#### Toán tử (Operation) |
|||
|
|||
"Toán tử" ở đây được nhắc tới là một trong các "phương thức" HTTP. |
|||
|
|||
Một trong những: |
|||
|
|||
* `POST` |
|||
* `GET` |
|||
* `PUT` |
|||
* `DELETE` |
|||
|
|||
...và một trong những cái còn lại: |
|||
|
|||
* `OPTIONS` |
|||
* `HEAD` |
|||
* `PATCH` |
|||
* `TRACE` |
|||
|
|||
Trong giao thức HTTP, bạn có thể giao tiếp trong mỗi đường dẫn sử dụng một (hoặc nhiều) trong các "phương thức này". |
|||
|
|||
--- |
|||
|
|||
Khi xây dựng các API, bạn thường sử dụng cụ thể các phương thức HTTP này để thực hiện một hành động cụ thể. |
|||
|
|||
Thông thường, bạn sử dụng |
|||
|
|||
* `POST`: để tạo dữ liệu. |
|||
* `GET`: để đọc dữ liệu. |
|||
* `PUT`: để cập nhật dữ liệu. |
|||
* `DELETE`: để xóa dữ liệu. |
|||
|
|||
Do đó, trong OpenAPI, mỗi phương thức HTTP được gọi là một "toán tử (operation)". |
|||
|
|||
Chúng ta cũng sẽ gọi chúng là "**các toán tử**". |
|||
|
|||
#### Định nghĩa moojt *decorator cho đường dẫn toán tử* |
|||
|
|||
```Python hl_lines="6" |
|||
{!../../../docs_src/first_steps/tutorial001.py!} |
|||
``` |
|||
|
|||
`@app.get("/")` nói **FastAPI** rằng hàm bên dưới có trách nhiệm xử lí request tới: |
|||
|
|||
* đường dẫn `/` |
|||
* sử dụng một <abbr title="an HTTP GET method">toán tử<code>get</code></abbr> |
|||
|
|||
!!! info Thông tin về "`@decorator`" |
|||
Cú pháp `@something` trong Python được gọi là một "decorator". |
|||
|
|||
Bạn đặt nó trên một hàm. Giống như một chiếc mũ xinh xắn (Tôi ddonas đó là lí do mà thuật ngữ này ra đời). |
|||
|
|||
Một "decorator" lấy một hàm bên dưới và thực hiện một vài thứ với nó. |
|||
|
|||
Trong trường hợp của chúng ta, decorator này nói **FastAPI** rằng hàm bên dưới ứng với **đường dẫn** `/` và một **toán tử** `get`. |
|||
|
|||
Nó là một "**decorator đường dẫn toán tử**". |
|||
|
|||
Bạn cũng có thể sử dụng với các toán tử khác: |
|||
|
|||
* `@app.post()` |
|||
* `@app.put()` |
|||
* `@app.delete()` |
|||
|
|||
Và nhiều hơn với các toán tử còn lại: |
|||
|
|||
* `@app.options()` |
|||
* `@app.head()` |
|||
* `@app.patch()` |
|||
* `@app.trace()` |
|||
|
|||
!!! tip |
|||
Bạn thoải mái sử dụng mỗi toán tử (phương thức HTTP) như bạn mơ ước. |
|||
|
|||
**FastAPI** không bắt buộc bất kì ý nghĩa cụ thể nào. |
|||
|
|||
Thông tin ở đây được biểu thị như là một chỉ dẫn, không phải là một yêu cầu bắt buộc. |
|||
|
|||
Ví dụ, khi sử dụng GraphQL bạn thông thường thực hiện tất cả các hành động chỉ bằng việc sử dụng các toán tử `POST`. |
|||
|
|||
### Step 4: Định nghĩa **hàm cho đường dẫn toán tử** |
|||
|
|||
Đây là "**hàm cho đường dẫn toán tử**": |
|||
|
|||
* **đường dẫn**: là `/`. |
|||
* **toán tử**: là `get`. |
|||
* **hàm**: là hàm bên dưới "decorator" (bên dưới `@app.get("/")`). |
|||
|
|||
```Python hl_lines="7" |
|||
{!../../../docs_src/first_steps/tutorial001.py!} |
|||
``` |
|||
|
|||
Đây là một hàm Python. |
|||
|
|||
Nó sẽ được gọi bởi **FastAPI** bất cứ khi nào nó nhận một request tới URL "`/`" sử dụng một toán tử `GET`. |
|||
|
|||
Trong trường hợp này, nó là một hàm `async`. |
|||
|
|||
--- |
|||
|
|||
Bạn cũng có thể định nghĩa nó như là một hàm thông thường thay cho `async def`: |
|||
|
|||
```Python hl_lines="7" |
|||
{!../../../docs_src/first_steps/tutorial003.py!} |
|||
``` |
|||
|
|||
!!! note |
|||
Nếu bạn không biết sự khác nhau, kiểm tra [Async: *"Trong khi vội vàng?"*](../async.md#in-a-hurry){.internal-link target=_blank}. |
|||
|
|||
### Bước 5: Nội dung trả về |
|||
|
|||
```Python hl_lines="8" |
|||
{!../../../docs_src/first_steps/tutorial001.py!} |
|||
``` |
|||
|
|||
Bạn có thể trả về một `dict`, `list`, một trong những giá trị đơn như `str`, `int`,... |
|||
|
|||
Bạn cũng có thể trả về Pydantic model (bạn sẽ thấy nhiều hơn về nó sau). |
|||
|
|||
Có nhiều object và model khác nhau sẽ được tự động chuyển đổi sang JSON (bao gồm cả ORM,...). Thử sử dụng loại ưa thích của bạn, nó có khả năng cao đã được hỗ trợ. |
|||
|
|||
## Tóm lại |
|||
|
|||
* Import `FastAPI`. |
|||
* Tạo một `app` instance. |
|||
* Viết một **decorator cho đường dẫn toán tử** (giống như `@app.get("/")`). |
|||
* Viết một **hàm cho đường dẫn toán tử** (giống như `def root(): ...` ở trên). |
|||
* Chạy server trong môi trường phát triển (giống như `uvicorn main:app --reload`). |
|||
@ -0,0 +1,80 @@ |
|||
# Hướng dẫn sử dụng |
|||
|
|||
Hướng dẫn này cho bạn thấy từng bước cách sử dụng **FastAPI** đa số các tính năng của nó. |
|||
|
|||
Mỗi phần được xây dựng từ những phần trước đó, nhưng nó được cấu trúc thành các chủ đề riêng biệt, do đó bạn có thể xem trực tiếp từng phần cụ thể bất kì để giải quyết những API cụ thể mà bạn cần. |
|||
|
|||
Nó cũng được xây dựng để làm việc như một tham chiếu trong tương lai. |
|||
|
|||
Do đó bạn có thể quay lại và tìm chính xác những gì bạn cần. |
|||
|
|||
## Chạy mã |
|||
|
|||
Tất cả các code block có thể được sao chép và sử dụng trực tiếp (chúng thực chất là các tệp tin Python đã được kiểm thử). |
|||
|
|||
Để chạy bất kì ví dụ nào, sao chép code tới tệp tin `main.py`, và bắt đầu `uvicorn` với: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ uvicorn main:app --reload |
|||
|
|||
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) |
|||
<span style="color: green;">INFO</span>: Started reloader process [28720] |
|||
<span style="color: green;">INFO</span>: Started server process [28722] |
|||
<span style="color: green;">INFO</span>: Waiting for application startup. |
|||
<span style="color: green;">INFO</span>: Application startup complete. |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
**Khuyến khích** bạn viết hoặc sao chép code, sửa và chạy nó ở local. |
|||
|
|||
Sử dụng nó trong trình soạn thảo của bạn thực sự cho bạn thấy những lợi ích của FastAPI, thấy được cách bạn viết code ít hơn, tất cả đều được type check, autocompletion,... |
|||
|
|||
--- |
|||
|
|||
## Cài đặt FastAPI |
|||
|
|||
Bước đầu tiên là cài đặt FastAPI. |
|||
|
|||
Với hướng dẫn này, bạn có thể muốn cài đặt nó với tất cả các phụ thuộc và tính năng tùy chọn: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ pip install "fastapi[all]" |
|||
|
|||
---> 100% |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
...dó cũng bao gồm `uvicorn`, bạn có thể sử dụng như một server để chạy code của bạn. |
|||
|
|||
!!! note |
|||
Bạn cũng có thể cài đặt nó từng phần. |
|||
|
|||
Đây là những gì bạn có thể sẽ làm một lần duy nhất bạn muốn triển khai ứng dụng của bạn lên production: |
|||
|
|||
``` |
|||
pip install fastapi |
|||
``` |
|||
|
|||
Cũng cài đặt `uvicorn` để làm việc như một server: |
|||
|
|||
``` |
|||
pip install "uvicorn[standard]" |
|||
``` |
|||
|
|||
Và tương tự với từng phụ thuộc tùy chọn mà bạn muốn sử dụng. |
|||
|
|||
## Hướng dẫn nâng cao |
|||
|
|||
Cũng có một **Hướng dẫn nâng cao** mà bạn có thể đọc nó sau **Hướng dẫn sử dụng**. |
|||
|
|||
**Hướng dẫn sử dụng nâng cao**, xây dựng dựa trên cái này, sử dụng các khái niệm tương tự, và dạy bạn những tính năng mở rộng. |
|||
|
|||
Nhưng bạn nên đọc **Hướng dẫn sử dụng** đầu tiên (những gì bạn đang đọc). |
|||
|
|||
Nó được thiết kế do đó bạn có thể xây dựng một ứng dụng hoàn chỉnh chỉ với **Hướng dẫn sử dụng**, và sau đó mở rộng nó theo các cách khác nhau, phụ thuộc vào những gì bạn cần, sử dụng một vài ý tưởng bổ sung từ **Hướng dẫn sử dụng nâng cao**. |
|||
@ -0,0 +1,470 @@ |
|||
<p align="center"> |
|||
<a href="https://fastapi.tiangolo.com"><img src="https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png" alt="FastAPI"></a> |
|||
</p> |
|||
<p align="center"> |
|||
<em>Ìlànà wẹ́ẹ́bù FastAPI, iṣẹ́ gíga, ó rọrùn láti kọ̀, o yára láti kóòdù, ó sì ṣetán fún iṣelọpọ ní lílo</em> |
|||
</p> |
|||
<p align="center"> |
|||
<a href="https://github.com/tiangolo/fastapi/actions?query=workflow%3ATest+event%3Apush+branch%3Amaster" target="_blank"> |
|||
<img src="https://github.com/tiangolo/fastapi/workflows/Test/badge.svg?event=push&branch=master" alt="Test"> |
|||
</a> |
|||
<a href="https://coverage-badge.samuelcolvin.workers.dev/redirect/tiangolo/fastapi" target="_blank"> |
|||
<img src="https://coverage-badge.samuelcolvin.workers.dev/tiangolo/fastapi.svg" alt="Coverage"> |
|||
</a> |
|||
<a href="https://pypi.org/project/fastapi" target="_blank"> |
|||
<img src="https://img.shields.io/pypi/v/fastapi?color=%2334D058&label=pypi%20package" alt="Package version"> |
|||
</a> |
|||
<a href="https://pypi.org/project/fastapi" target="_blank"> |
|||
<img src="https://img.shields.io/pypi/pyversions/fastapi.svg?color=%2334D058" alt="Supported Python versions"> |
|||
</a> |
|||
</p> |
|||
|
|||
--- |
|||
|
|||
**Àkọsílẹ̀**: <a href="https://fastapi.tiangolo.com" target="_blank">https://fastapi.tiangolo.com</a> |
|||
|
|||
**Orisun Kóòdù**: <a href="https://github.com/tiangolo/fastapi" target="_blank">https://github.com/tiangolo/fastapi</a> |
|||
|
|||
--- |
|||
|
|||
FastAPI jẹ́ ìgbàlódé, tí ó yára (iṣẹ-giga), ìlànà wẹ́ẹ́bù fún kikọ àwọn API pẹ̀lú Python 3.7+ èyí tí ó da lori àwọn ìtọ́kasí àmì irúfẹ́ Python. |
|||
|
|||
Àwọn ẹya pàtàkì ni: |
|||
|
|||
* **Ó yára**: Iṣẹ tí ó ga púpọ̀, tí ó wa ni ibamu pẹ̀lú **NodeJS** àti **Go** (ọpẹ si Starlette àti Pydantic). [Ọkan nínú àwọn ìlànà Python ti o yára jùlọ ti o wa](#performance). |
|||
* **Ó yára láti kóòdù**: O mu iyara pọ si láti kọ àwọn ẹya tuntun kóòdù nipasẹ "Igba ìdá ọgọ́rùn-ún" (i.e. 200%) si "ọ̀ọ́dúrún ìdá ọgọ́rùn-ún" (i.e. 300%). |
|||
* **Àìtọ́ kékeré**: O n din aṣiṣe ku bi ọgbon ìdá ọgọ́rùn-ún (i.e. 40%) ti eda eniyan (oṣiṣẹ kóòdù) fa. * |
|||
* **Ọgbọ́n àti ìmọ̀**: Atilẹyin olootu nla. <abbr title="a tun le pe ni olùrànlọ́wọ́ alaifiọwọkan alaifọwọyi, olùpari iṣẹ-ṣiṣe, Oloye">Ìparí</abbr> nibi gbogbo. Àkókò díẹ̀ nipa wíwá ibi tí ìṣòro kóòdù wà. |
|||
* **Irọrun**: A kọ kí ó le rọrun láti lo àti láti kọ ẹkọ nínú rè. Ó máa fún ọ ní àkókò díẹ̀ látı ka àkọsílẹ. |
|||
* **Ó kúkurú ní kikọ**: Ó dín àtúnkọ àti àtúntò kóòdù kù. Ìkéde àṣàyàn kọ̀ọ̀kan nínú rẹ̀ ní ọ̀pọ̀lọpọ̀ àwọn ìlò. O ṣe iranlọwọ láti má ṣe ní ọ̀pọ̀lọpọ̀ àṣìṣe. |
|||
* **Ó lágbára**: Ó ń ṣe àgbéjáde kóòdù tí ó ṣetán fún ìṣelọ́pọ̀. Pẹ̀lú àkọsílẹ̀ tí ó máa ṣàlàyé ara rẹ̀ fún ẹ ní ìbáṣepọ̀ aládàáṣiṣẹ́ pẹ̀lú rè. |
|||
* **Ajohunše/Ìtọ́kasí**: Ó da lori (àti ibamu ni kikun pẹ̀lú) àwọn ìmọ ajohunše/ìtọ́kasí fún àwọn API: <a href="https://github.com/OAI/OpenAPI-Specification" class="external-link" target="_blank">OpenAPI</a> (èyí tí a mọ tẹlẹ si Swagger) àti <a href="https://json-schema.org/" class="external-link" target="_blank">JSON Schema</a>. |
|||
|
|||
<small>* iṣiro yi da lori àwọn idanwo tí ẹgbẹ ìdàgbàsókè FastAPI ṣe, nígbàtí wọn kọ àwọn ohun elo iṣelọpọ kóòdù pẹ̀lú rẹ.</small> |
|||
|
|||
## Àwọn onígbọ̀wọ́ |
|||
|
|||
<!-- sponsors --> |
|||
|
|||
{% if sponsors %} |
|||
{% for sponsor in sponsors.gold -%} |
|||
<a href="{{ sponsor.url }}" target="_blank" title="{{ sponsor.title }}"><img src="{{ sponsor.img }}" style="border-radius:15px"></a> |
|||
{% endfor -%} |
|||
{%- for sponsor in sponsors.silver -%} |
|||
<a href="{{ sponsor.url }}" target="_blank" title="{{ sponsor.title }}"><img src="{{ sponsor.img }}" style="border-radius:15px"></a> |
|||
{% endfor %} |
|||
{% endif %} |
|||
|
|||
<!-- /sponsors --> |
|||
|
|||
<a href="https://fastapi.tiangolo.com/fastapi-people/#sponsors" class="external-link" target="_blank">Àwọn onígbọ̀wọ́ míràn</a> |
|||
|
|||
## Àwọn ero àti èsì |
|||
|
|||
"_[...] Mò ń lo **FastAPI** púpọ̀ ní lẹ́nu àìpẹ́ yìí. [...] Mo n gbero láti lo o pẹ̀lú àwọn ẹgbẹ mi fún gbogbo iṣẹ **ML wa ni Microsoft**. Diẹ nínú wọn ni afikun ti ifilelẹ àwọn ẹya ara ti ọja **Windows** wa pẹ̀lú àwọn ti **Office**._" |
|||
|
|||
<div style="text-align: right; margin-right: 10%;">Kabir Khan - <strong>Microsoft</strong> <a href="https://github.com/tiangolo/fastapi/pull/26" target="_blank"><small>(ref)</small></a></div> |
|||
|
|||
--- |
|||
|
|||
"_A gba àwọn ohun èlò ìwé afọwọkọ **FastAPI** tí kò yí padà láti ṣẹ̀dá olùpín **REST** tí a lè béèrè lọ́wọ́ rẹ̀ láti gba **àsọtẹ́lẹ̀**. [fún Ludwig]_" |
|||
|
|||
<div style="text-align: right; margin-right: 10%;">Piero Molino, Yaroslav Dudin, and Sai Sumanth Miryala - <strong>Uber</strong> <a href="https://eng.uber.com/ludwig-v0-2/" target="_blank"><small>(ref)</small></a></div> |
|||
|
|||
--- |
|||
|
|||
"_**Netflix** ni inudidun láti kede itusilẹ orisun kóòdù ti ìlànà iṣọkan **iṣakoso Ìṣòro** wa: **Ìfiránṣẹ́**! [a kọ pẹ̀lú **FastAPI**]_" |
|||
|
|||
<div style="text-align: right; margin-right: 10%;">Kevin Glisson, Marc Vilanova, Forest Monsen - <strong>Netflix</strong> <a href="https://netflixtechblog.com/introducing-dispatch-da4b8a2a8072" target="_blank"><small>(ref)</small></a></div> |
|||
|
|||
--- |
|||
|
|||
"_Inú mi dùn púpọ̀ nípa **FastAPI**. Ó mú inú ẹnì dùn púpọ̀!_" |
|||
|
|||
<div style="text-align: right; margin-right: 10%;">Brian Okken - <strong><a href="https://pythonbytes.fm/episodes/show/123/time-to-right-the-py-wrongs?time_in_sec=855" target="_blank">Python Bytes</a> podcast host</strong> <a href="https://twitter.com/brianokken/status/1112220079972728832" target="_blank"><small>(ref)</small></a></div> |
|||
|
|||
--- |
|||
|
|||
"_Ní tòótọ́, ohun tí o kọ dára ó sì tún dán. Ní ọ̀pọ̀lọpọ̀ ọ̀nà, ohun tí mo fẹ́ kí **Hug** jẹ́ nìyẹn - ó wúni lórí gan-an láti rí ẹnìkan tí ó kọ́ nǹkan bí èyí._" |
|||
|
|||
<div style="text-align: right; margin-right: 10%;">Timothy Crosley - <strong><a href="https://www.hug.rest/" target="_blank">Hug</a> creator</strong> <a href="https://news.ycombinator.com/item?id=19455465" target="_blank"><small>(ref)</small></a></div> |
|||
|
|||
--- |
|||
|
|||
"_Ti o ba n wa láti kọ ọkan **ìlànà igbalode** fún kikọ àwọn REST API, ṣayẹwo **FastAPI** [...] Ó yára, ó rọrùn láti lò, ó sì rọrùn láti kọ́[...]_" |
|||
|
|||
"_A ti yipada si **FastAPI** fún **APIs** wa [...] Mo lérò pé wà á fẹ́ràn rẹ̀ [...]_" |
|||
|
|||
<div style="text-align: right; margin-right: 10%;">Ines Montani - Matthew Honnibal - <strong><a href="https://explosion.ai" target="_blank">Explosion AI</a> founders - <a href="https://spacy.io" target="_blank">spaCy</a> creators</strong> <a href="https://twitter.com/_inesmontani/status/1144173225322143744" target="_blank"><small>(ref)</small></a> - <a href="https://twitter.com/honnibal/status/1144031421859655680" target="_blank"><small>(ref)</small></a></div> |
|||
|
|||
--- |
|||
|
|||
"_Ti ẹnikẹni ba n wa láti kọ iṣelọpọ API pẹ̀lú Python, èmi yóò ṣe'dúró fún **FastAPI**. Ó jẹ́ ohun tí **àgbékalẹ̀ rẹ̀ lẹ́wà**, **ó rọrùn láti lò** àti wipe ó ni **ìwọ̀n gíga**, o tí dí **bọtini paati** nínú alakọkọ API ìdàgbàsókè kikọ fún wa, àti pe o ni ipa lori adaṣiṣẹ àti àwọn iṣẹ gẹ́gẹ́ bíi Onímọ̀-ẹ̀rọ TAC tí órí Íńtánẹ́ẹ̀tì_" |
|||
|
|||
<div style="text-align: right; margin-right: 10%;">Deon Pillsbury - <strong>Cisco</strong> <a href="https://www.linkedin.com/posts/deonpillsbury_cisco-cx-python-activity-6963242628536487936-trAp/" target="_blank"><small>(ref)</small></a></div> |
|||
|
|||
--- |
|||
|
|||
## **Typer**, FastAPI ti CLIs |
|||
|
|||
<a href="https://typer.tiangolo.com" target="_blank"><img src="https://typer.tiangolo.com/img/logo-margin/logo-margin-vector.svg" style="width: 20%;"></a> |
|||
|
|||
Ti o ba n kọ ohun èlò <abbr title="Command Line Interface">CLI</abbr> láti ṣeé lọ nínú ohun èlò lori ebute kọmputa dipo API, ṣayẹwo <a href="https://typer.tiangolo.com/" class="external-link" target="_blank">**Typer**</a>. |
|||
|
|||
**Typer** jẹ́ àbúrò ìyá FastAPI kékeré. Àti pé wọ́n kọ́ láti jẹ́ **FastAPI ti CLIs**. ⌨️ 🚀 |
|||
|
|||
## Èròjà |
|||
|
|||
Python 3.7+ |
|||
|
|||
FastAPI dúró lórí àwọn èjìká tí àwọn òmíràn: |
|||
|
|||
* <a href="https://www.starlette.io/" class="external-link" target="_blank">Starlette</a> fún àwọn ẹ̀yà ayélujára. |
|||
* <a href="https://pydantic-docs.helpmanual.io/" class="external-link" target="_blank">Pydantic</a> fún àwọn ẹ̀yà àkójọf'áyẹ̀wò. |
|||
|
|||
## Fifi sórí ẹrọ |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ pip install fastapi |
|||
|
|||
---> 100% |
|||
``` |
|||
|
|||
</div> |
|||
Iwọ yóò tún nílò olupin ASGI, fún iṣelọpọ bii <a href="https://www.uvicorn.org" class="external-link" target="_blank">Uvicorn</a> tabi <a href="https://github.com/pgjones/hypercorn" class="external-link" target="_blank">Hypercorn</a>. |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ pip install "uvicorn[standard]" |
|||
|
|||
---> 100% |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
## Àpẹẹrẹ |
|||
|
|||
### Ṣẹ̀dá rẹ̀ |
|||
|
|||
* Ṣẹ̀dá fáìlì `main.py (èyí tíí ṣe, akọkọ.py)` pẹ̀lú: |
|||
|
|||
```Python |
|||
from typing import Union |
|||
|
|||
from fastapi import FastAPI |
|||
|
|||
app = FastAPI() |
|||
|
|||
|
|||
@app.get("/") |
|||
def read_root(): |
|||
return {"Hello": "World"} |
|||
|
|||
|
|||
@app.get("/items/{item_id}") |
|||
def read_item(item_id: int, q: Union[str, None] = None): |
|||
return {"item_id": item_id, "q": q} |
|||
``` |
|||
|
|||
<details markdown="1"> |
|||
<summary>Tàbí lò <code>async def</code>...</summary> |
|||
|
|||
Tí kóòdù rẹ̀ bá ń lò `async` / `await`, lò `async def`: |
|||
|
|||
```Python hl_lines="9 14" |
|||
from typing import Union |
|||
|
|||
from fastapi import FastAPI |
|||
|
|||
app = FastAPI() |
|||
|
|||
|
|||
@app.get("/") |
|||
async def read_root(): |
|||
return {"Hello": "World"} |
|||
|
|||
|
|||
@app.get("/items/{item_id}") |
|||
async def read_item(item_id: int, q: Union[str, None] = None): |
|||
return {"item_id": item_id, "q": q} |
|||
``` |
|||
|
|||
**Akiyesi**: |
|||
|
|||
Tí o kò bá mọ̀, ṣàyẹ̀wò ibi tí a ti ní _"In a hurry?"_ (i.e. _"Ní kíákíá?"_) nípa <a href="https://fastapi.tiangolo.com/async/#in-a-hurry" target="_blank">`async` and `await` nínú àkọsílẹ̀</a>. |
|||
|
|||
</details> |
|||
|
|||
### Mu ṣiṣẹ |
|||
|
|||
Mú olupin ṣiṣẹ pẹ̀lú: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ uvicorn main:app --reload |
|||
|
|||
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) |
|||
INFO: Started reloader process [28720] |
|||
INFO: Started server process [28722] |
|||
INFO: Waiting for application startup. |
|||
INFO: Application startup complete. |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
<details markdown="1"> |
|||
<summary>Nipa aṣẹ kóòdù náà <code>uvicorn main:app --reload</code>...</summary> |
|||
|
|||
Àṣẹ `uvicorn main:app` ń tọ́ka sí: |
|||
|
|||
* `main`: fáìlì náà 'main.py' (Python "module"). |
|||
* `app` jẹ object( i.e. nǹkan) tí a ṣẹ̀dá nínú `main.py` pẹ̀lú ilà `app = FastAPI()`. |
|||
* `--reload`: èyí yóò jẹ́ ki olupin tún bẹ̀rẹ̀ lẹ́hìn àwọn àyípadà kóòdù. Jọ̀wọ́, ṣe èyí fún ìdàgbàsókè kóòdù nìkan, má ṣe é ṣe lori àgbéjáde kóòdù tabi fún iṣelọpọ kóòdù. |
|||
|
|||
|
|||
</details> |
|||
|
|||
### Ṣayẹwo rẹ |
|||
|
|||
Ṣii aṣàwákiri kọ̀ǹpútà rẹ ni <a href="http://127.0.0.1:8000/items/5?q=somequery" class="external-link" target="_blank">http://127.0.0.1:8000/items/5?q=somequery</a>. |
|||
|
|||
Ìwọ yóò sì rí ìdáhùn JSON bíi: |
|||
|
|||
```JSON |
|||
{"item_id": 5, "q": "somequery"} |
|||
``` |
|||
|
|||
O tí ṣẹ̀dá API èyí tí yóò: |
|||
|
|||
* Gbà àwọn ìbéèrè HTTP ni àwọn _ipa ọ̀nà_ `/` àti `/items/{item_id}`. |
|||
* Èyí tí àwọn _ipa ọ̀nà_ (i.e. _paths_) méjèèjì gbà àwọn <em>iṣẹ</em> `GET` (a tun mọ si _àwọn ọna_ HTTP). |
|||
* Èyí tí _ipa ọ̀nà_ (i.e. _paths_) `/items/{item_id}` ní _àwọn ohun-ini ipa ọ̀nà_ tí ó yẹ kí ó jẹ́ `int` i.e. `ÒǸKÀ`. |
|||
* Èyí tí _ipa ọ̀nà_ (i.e. _paths_) `/items/{item_id}` ní àṣàyàn `str` _àwọn ohun-ini_ (i.e. _query parameter_) `q`. |
|||
|
|||
### Ìbáṣepọ̀ àkọsílẹ̀ API |
|||
|
|||
Ní báyìí, lọ sí <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>. |
|||
|
|||
Lẹ́yìn náà, iwọ yóò rí ìdáhùn àkọsílẹ̀ API tí ó jẹ́ ìbáṣepọ̀ alaifọwọyi/aládàáṣiṣẹ́ (tí a pèṣè nípaṣẹ̀ <a href="https://github.com/swagger-api/swagger-ui" class="external-link" target="_blank">Swagger UI</a>): |
|||
|
|||
 |
|||
|
|||
### Ìdàkejì àkọsílẹ̀ API |
|||
|
|||
Ní báyìí, lọ sí <a href="http://127.0.0.1:8000/redoc" class="external-link" target="_blank">http://127.0.0.1:8000/redoc</a>. |
|||
|
|||
Wà á rí àwọn àkọsílẹ̀ aládàáṣiṣẹ́ mìíràn (tí a pese nipasẹ <a href="https://github.com/Rebilly/ReDoc" class="external-link" target="_blank">ReDoc</a>): |
|||
|
|||
 |
|||
|
|||
## Àpẹẹrẹ ìgbésókè mìíràn |
|||
|
|||
Ní báyìí ṣe àtúnṣe fáìlì `main.py` láti gba kókó èsì láti inú ìbéèrè `PUT`. |
|||
|
|||
Ní báyìí, ṣe ìkéde kókó èsì API nínú kóòdù rẹ nipa lílo àwọn ìtọ́kasí àmì irúfẹ́ Python, ọpẹ́ pàtàkìsi sí Pydantic. |
|||
|
|||
```Python hl_lines="4 9-12 25-27" |
|||
from typing import Union |
|||
|
|||
from fastapi import FastAPI |
|||
from pydantic import BaseModel |
|||
|
|||
app = FastAPI() |
|||
|
|||
|
|||
class Item(BaseModel): |
|||
name: str |
|||
price: float |
|||
is_offer: Union[bool, None] = None |
|||
|
|||
|
|||
@app.get("/") |
|||
def read_root(): |
|||
return {"Hello": "World"} |
|||
|
|||
|
|||
@app.get("/items/{item_id}") |
|||
def read_item(item_id: int, q: Union[str, None] = None): |
|||
return {"item_id": item_id, "q": q} |
|||
|
|||
|
|||
@app.put("/items/{item_id}") |
|||
def update_item(item_id: int, item: Item): |
|||
return {"item_name": item.name, "item_id": item_id} |
|||
``` |
|||
|
|||
Olupin yóò tún ṣe àtúnṣe laifọwọyi/aládàáṣiṣẹ́ (nítorí wípé ó se àfikún `-reload` si àṣẹ kóòdù `uvicorn` lókè). |
|||
|
|||
### Ìbáṣepọ̀ ìgbésókè àkọsílẹ̀ API |
|||
|
|||
Ní báyìí, lọ sí <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>. |
|||
|
|||
* Ìbáṣepọ̀ àkọsílẹ̀ API yóò ṣe imudojuiwọn àkọsílẹ̀ API laifọwọyi, pẹ̀lú kókó èsì ìdáhùn API tuntun: |
|||
|
|||
 |
|||
|
|||
* Tẹ bọtini "Gbiyanju rẹ" i.e. "Try it out", yóò gbà ọ́ láàyè láti jẹ́ kí ó tẹ́ àlàyé tí ó nílò kí ó le sọ̀rọ̀ tààrà pẹ̀lú API: |
|||
|
|||
 |
|||
|
|||
* Lẹhinna tẹ bọtini "Ṣiṣe" i.e. "Execute", olùmúlò (i.e. user interface) yóò sọrọ pẹ̀lú API rẹ, yóò ṣe afiranṣẹ àwọn èròjà, pàápàá jùlọ yóò gba àwọn àbájáde yóò si ṣafihan wọn loju ìbòjú: |
|||
|
|||
 |
|||
|
|||
### Ìdàkejì ìgbésókè àkọsílẹ̀ API |
|||
|
|||
Ní báyìí, lọ sí <a href="http://127.0.0.1:8000/redoc" class="external-link" target="_blank">http://127.0.0.1:8000/redoc</a>. |
|||
|
|||
* Ìdàkejì àkọsílẹ̀ API yóò ṣ'afihan ìbéèrè èròjà/pàrámítà tuntun àti kókó èsì ti API: |
|||
|
|||
 |
|||
|
|||
### Àtúnyẹ̀wò |
|||
|
|||
Ni akopọ, ìwọ yóò kéde ni **kete** àwọn iru èròjà/pàrámítà, kókó èsì API, abbl (i.e. àti bẹbẹ lọ), bi àwọn èròjà iṣẹ. |
|||
|
|||
O ṣe ìyẹn pẹ̀lú irúfẹ́ àmì ìtọ́kasí ìgbàlódé Python. |
|||
|
|||
O ò nílò láti kọ́ síńtáàsì tuntun, ìlànà tàbí ọ̀wọ́ kíláàsì kan pàtó, abbl (i.e. àti bẹbẹ lọ). |
|||
|
|||
Ìtọ́kasí **Python 3.7+** |
|||
|
|||
Fún àpẹẹrẹ, fún `int`: |
|||
|
|||
```Python |
|||
item_id: int |
|||
``` |
|||
|
|||
tàbí fún àwòṣe `Item` tí ó nira díẹ̀ síi: |
|||
|
|||
```Python |
|||
item: Item |
|||
``` |
|||
|
|||
... àti pẹ̀lú ìkéde kan ṣoṣo yẹn ìwọ yóò gbà: |
|||
|
|||
* Atilẹyin olootu, pẹ̀lú: |
|||
* Pipari. |
|||
* Àyẹ̀wò irúfẹ́ àmì ìtọ́kasí. |
|||
* Ìfọwọ́sí àkójọf'áyẹ̀wò (i.e. data): |
|||
* Aṣiṣe alaifọwọyi/aládàáṣiṣẹ́ àti aṣiṣe ti ó hàn kedere nígbàtí àwọn àkójọf'áyẹ̀wò (i.e. data) kò wulo tabi tí kò fẹsẹ̀ múlẹ̀. |
|||
* Ìfọwọ́sí fún ohun elo JSON tí ó jìn gan-an. |
|||
* <abbr title="also known as: serialization, parsing, marshalling">Ìyípadà</abbr> tí input àkójọf'áyẹ̀wò: tí ó wà láti nẹtiwọọki si àkójọf'áyẹ̀wò àti irúfẹ́ àmì ìtọ́kasí Python. Ó ń ka láti: |
|||
* JSON. |
|||
* èròjà ọ̀nà tí ò gbé gbà. |
|||
* èròjà ìbéèrè. |
|||
* Àwọn Kúkì |
|||
* Àwọn Àkọlé |
|||
* Àwọn Fọọmu |
|||
* Àwọn Fáìlì |
|||
* <abbr title="a tún má ń pè ni: serialization, parsing, marshalling">Ìyípadà</abbr> èsì àkójọf'áyẹ̀wò: yíyípadà láti àkójọf'áyẹ̀wò àti irúfẹ́ àmì ìtọ́kasí Python si nẹtiwọọki (gẹ́gẹ́ bí JSON): |
|||
* Yí irúfẹ́ àmì ìtọ́kasí padà (`str`, `int`, `float`, `bool`, `list`, abbl i.e. àti bèbè ló). |
|||
* Àwọn ohun èlò `datetime`. |
|||
* Àwọn ohun èlò `UUID`. |
|||
* Àwọn awoṣẹ́ ibi ìpamọ́ àkójọf'áyẹ̀wò. |
|||
* ...àti ọ̀pọ̀lọpọ̀ díẹ̀ síi. |
|||
* Ìbáṣepọ̀ àkọsílẹ̀ API aládàáṣiṣẹ́, pẹ̀lú ìdàkejì àgbékalẹ̀-àwọn-olùmúlò (i.e user interfaces) méjì: |
|||
* Àgbékalẹ̀-olùmúlò Swagger. |
|||
* ReDoc. |
|||
|
|||
--- |
|||
|
|||
Nisinsin yi, tí ó padà sí àpẹẹrẹ ti tẹ́lẹ̀, **FastAPI** yóò: |
|||
|
|||
* Fọwọ́ sí i pé `item_id` wà nínú ọ̀nà ìbéèrè HTTP fún `GET` àti `PUT`. |
|||
* Fọwọ́ sí i pé `item_id` jẹ́ irúfẹ́ àmì ìtọ́kasí `int` fún ìbéèrè HTTP `GET` àti `PUT`. |
|||
* Tí kìí bá ṣe bẹ, oníbàárà yóò ríi àṣìṣe tí ó wúlò, kedere. |
|||
* Ṣàyẹ̀wò bóyá ìbéèrè àṣàyàn pàrámítà kan wà tí orúkọ rẹ̀ ń jẹ́ `q` (gẹ́gẹ́ bíi `http://127.0.0.1:8000/items/foo?q=somequery`) fún ìbéèrè HTTP `GET`. |
|||
* Bí wọ́n ṣe kéde pàrámítà `q` pẹ̀lú `= None`, ó jẹ́ àṣàyàn (i.e optional). |
|||
* Láìsí `None` yóò nílò (gẹ́gẹ́ bí kókó èsì ìbéèrè HTTP ṣe wà pẹ̀lú `PUT`). |
|||
* Fún àwọn ìbéèrè HTTP `PUT` sí `/items/{item_id}`, kà kókó èsì ìbéèrè HTTP gẹ́gẹ́ bí JSON: |
|||
* Ṣàyẹ̀wò pé ó ní àbùdá tí ó nílò èyí tíí ṣe `name` i.e. `orúkọ` tí ó yẹ kí ó jẹ́ `str`. |
|||
* Ṣàyẹ̀wò pé ó ní àbùdá tí ó nílò èyí tíí ṣe `price` i.e. `iye` tí ó gbọ́dọ̀ jẹ́ `float`. |
|||
* Ṣàyẹ̀wò pé ó ní àbùdá àṣàyàn `is_offer`, tí ó yẹ kí ó jẹ́ `bool`, tí ó bá wà níbẹ̀. |
|||
* Gbogbo èyí yóò tún ṣiṣẹ́ fún àwọn ohun èlò JSON tí ó jìn gidi gan-an. |
|||
* Yìí padà láti àti sí JSON lai fi ọwọ́ yi. |
|||
* Ṣe àkọsílẹ̀ ohun gbogbo pẹ̀lú OpenAPI, èyí tí yóò wà ní lílo nípaṣẹ̀: |
|||
* Àwọn ètò àkọsílẹ̀ ìbáṣepọ̀. |
|||
* Aládàáṣiṣẹ́ oníbárà èlètò tíí ṣẹ̀dá kóòdù, fún ọ̀pọ̀lọpọ̀ àwọn èdè. |
|||
* Pese àkọsílẹ̀ òní ìbáṣepọ̀ ti àwọn àgbékalẹ̀ ayélujára méjì tààrà. |
|||
|
|||
--- |
|||
|
|||
A ń ṣẹ̀ṣẹ̀ ń mú ẹyẹ bọ́ làpò ní, ṣùgbọ́n ó ti ni òye bí gbogbo rẹ̀ ṣe ń ṣiṣẹ́. |
|||
|
|||
Gbiyanju láti yí ìlà padà pẹ̀lú: |
|||
|
|||
```Python |
|||
return {"item_name": item.name, "item_id": item_id} |
|||
``` |
|||
|
|||
...láti: |
|||
|
|||
```Python |
|||
... "item_name": item.name ... |
|||
``` |
|||
|
|||
...ṣí: |
|||
|
|||
```Python |
|||
... "item_price": item.price ... |
|||
``` |
|||
|
|||
.. kí o sì wo bí olóòtú rẹ yóò ṣe parí àwọn àbùdá náà fúnra rẹ̀, yóò sì mọ irúfẹ́ wọn: |
|||
|
|||
 |
|||
|
|||
Fún àpẹẹrẹ pípé síi pẹ̀lú àwọn àbùdá mìíràn, wo <a href="https://fastapi.tiangolo.com/tutorial/">Ìdánilẹ́kọ̀ọ́ - Ìtọ́sọ́nà Olùmúlò</a>. |
|||
|
|||
**Itaniji gẹ́gẹ́ bí isọ'ye**: ìdánilẹ́kọ̀ọ́ - itọsọna olùmúlò pẹ̀lú: |
|||
|
|||
* Ìkéde àṣàyàn **pàrámítà** láti àwọn oriṣiriṣi ibòmíràn gẹ́gẹ́ bíi: àwọn **àkọlé èsì API**, **kúkì**, **ààyè fọọmu**, àti **fáìlì**. |
|||
* Bíi ó ṣe lé ṣètò **àwọn ìdíwọ́ ìfọwọ́sí** bí `maximum_length` tàbí `regex`. |
|||
* Ó lágbára púpọ̀ ó sì rọrùn láti lo ètò **<abbr title="a tún mọ̀ sí ìrìnṣẹ́, àwọn ohun àmúlò iṣẹ́, olupese, àwọn ohun àfikún ">Àfikún Ìgbẹ́kẹ̀lé Kóòdù</abbr>**. |
|||
* Ààbò àti ìfọwọ́sowọ́pọ̀, pẹ̀lú àtìlẹ́yìn fún **OAuth2** pẹ̀lú **àmì JWT** àti **HTTP Ipilẹ ìfọwọ́sowọ́pọ̀**. |
|||
* Àwọn ìlànà ìlọsíwájú (ṣùgbọ́n tí ó rọrùn bákan náà) fún ìkéde **àwọn àwòṣe JSON tó jinlẹ̀** (ọpẹ́ pàtàkìsi sí Pydantic). |
|||
* Iṣọpọ **GraphQL** pẹ̀lú <a href="https://strawberry.rocks" class="external-link" target="_blank">Strawberry</a> àti àwọn ohun èlò ìwé kóòdù afọwọkọ mìíràn tí kò yí padà. |
|||
* Ọpọlọpọ àwọn àfikún àwọn ẹ̀yà (ọpẹ́ pàtàkìsi sí Starlette) bí: |
|||
* **WebSockets** |
|||
* àwọn ìdánwò tí ó rọrùn púpọ̀ lórí HTTPX àti `pytest` |
|||
* **CORS** |
|||
* **Cookie Sessions** |
|||
* ...àti síwájú síi. |
|||
|
|||
## Ìṣesí |
|||
|
|||
Àwọn àlá TechEmpower fi hàn pé **FastAPI** ń ṣiṣẹ́ lábẹ́ Uvicorn gẹ́gẹ́ bí <a href="https://www.techempower.com/benchmarks/#section=test&runid=7464e520-0dc2-473d-bd34-dbdfd7e85911&hw=ph&test=query&l=zijzen-7" class="external-link" target="_blank">ọ̀kan lára àwọn ìlànà Python tí ó yára jùlọ tí ó wà</a>, ní ìsàlẹ̀ Starlette àti Uvicorn fúnra wọn (tí FastAPI ń lò fúnra rẹ̀). (*) |
|||
|
|||
Láti ní òye síi nípa rẹ̀, wo abala àwọn <a href="https://fastapi.tiangolo.com/benchmarks/" class="internal-link" target="_blank">Àlá</a>. |
|||
|
|||
## Àṣàyàn Àwọn Àfikún Ìgbẹ́kẹ̀lé Kóòdù |
|||
|
|||
Èyí tí Pydantic ń lò: |
|||
|
|||
* <a href="https://github.com/JoshData/python-email-validator" target="_blank"><code>email_validator</code></a> - fún ifọwọsi ímeèlì. |
|||
* <a href="https://docs.pydantic.dev/latest/usage/pydantic_settings/" target="_blank"><code>pydantic-settings</code></a> - fún ètò ìsàkóso. |
|||
* <a href="https://docs.pydantic.dev/latest/usage/types/extra_types/extra_types/" target="_blank"><code>pydantic-extra-types</code></a> - fún àfikún oríṣi láti lọ pẹ̀lú Pydantic. |
|||
|
|||
Èyí tí Starlette ń lò: |
|||
|
|||
* <a href="https://www.python-httpx.org" target="_blank"><code>httpx</code></a> - Nílò tí ó bá fẹ́ láti lọ `TestClient`. |
|||
* <a href="https://jinja.palletsprojects.com" target="_blank"><code>jinja2</code></a> - Nílò tí ó bá fẹ́ láti lọ iṣeto awoṣe aiyipada. |
|||
* <a href="https://andrew-d.github.io/python-multipart/" target="_blank"><code>python-multipart</code></a> - Nílò tí ó bá fẹ́ láti ṣe àtìlẹ́yìn fún <abbr title="tí ó se ìyípadà ọ̀rọ̀-ìyọ̀/òkun-ọ̀rọ̀ tí ó wà láti ìbéèrè HTTP sí inú àkójọf'áyẹ̀wò Python">"àyẹ̀wò"</abbr> fọọmu, pẹ̀lú `request.form()`. |
|||
* <a href="https://pythonhosted.org/itsdangerous/" target="_blank"><code>itsdangerous</code></a> - Nílò fún àtìlẹ́yìn `SessionMiddleware`. |
|||
* <a href="https://pyyaml.org/wiki/PyYAMLDocumentation" target="_blank"><code>pyyaml</code></a> - Nílò fún àtìlẹ́yìn Starlette's `SchemaGenerator` (ó ṣe ṣe kí ó má nílò rẹ̀ fún FastAPI). |
|||
* <a href="https://github.com/esnme/ultrajson" target="_blank"><code>ujson</code></a> - Nílò tí ó bá fẹ́ láti lọ `UJSONResponse`. |
|||
|
|||
Èyí tí FastAPI / Starlette ń lò: |
|||
|
|||
* <a href="https://www.uvicorn.org" target="_blank"><code>uvicorn</code></a> - Fún olupin tí yóò sẹ́ àmúyẹ àti tí yóò ṣe ìpèsè fún iṣẹ́ rẹ tàbí ohun èlò rẹ. |
|||
* <a href="https://github.com/ijl/orjson" target="_blank"><code>orjson</code></a> - Nílò tí ó bá fẹ́ láti lọ `ORJSONResponse`. |
|||
|
|||
Ó lè fi gbogbo àwọn wọ̀nyí sórí ẹrọ pẹ̀lú `pip install "fastapi[all]"`. |
|||
|
|||
## Iwe-aṣẹ |
|||
|
|||
Iṣẹ́ yìí ni iwe-aṣẹ lábẹ́ àwọn òfin tí iwe-aṣẹ MIT. |
|||
@ -0,0 +1 @@ |
|||
INHERIT: ../en/mkdocs.yml |
|||
@ -0,0 +1,266 @@ |
|||
# 生成客户端 |
|||
|
|||
因为 **FastAPI** 是基于OpenAPI规范的，自然您可以使用许多相匹配的工具，包括自动生成API文档 (由 Swagger UI 提供)。 |
|||
|
|||
一个不太明显而又特别的优势是，你可以为你的API针对不同的**编程语言**来**生成客户端**(有时候被叫做 <abbr title="Software Development Kits">**SDKs**</abbr> )。 |
|||
|
|||
## OpenAPI 客户端生成 |
|||
|
|||
有许多工具可以从**OpenAPI**生成客户端。 |
|||
|
|||
一个常见的工具是 <a href="https://openapi-generator.tech/" class="external-link" target="_blank">OpenAPI Generator</a>。 |
|||
|
|||
如果您正在开发**前端**，一个非常有趣的替代方案是 <a href="https://github.com/ferdikoomen/openapi-typescript-codegen" class="external-link" target="_blank">openapi-typescript-codegen</a>。 |
|||
|
|||
## 生成一个 TypeScript 前端客户端 |
|||
|
|||
让我们从一个简单的 FastAPI 应用开始： |
|||
|
|||
=== "Python 3.9+" |
|||
|
|||
```Python hl_lines="7-9 12-13 16-17 21" |
|||
{!> ../../../docs_src/generate_clients/tutorial001_py39.py!} |
|||
``` |
|||
|
|||
=== "Python 3.6+" |
|||
|
|||
```Python hl_lines="9-11 14-15 18 19 23" |
|||
{!> ../../../docs_src/generate_clients/tutorial001.py!} |
|||
``` |
|||
|
|||
请注意，*路径操作* 定义了他们所用于请求数据和回应数据的模型，所使用的模型是`Item` 和 `ResponseMessage`。 |
|||
|
|||
### API 文档 |
|||
|
|||
如果您访问API文档，您将看到它具有在请求中发送和在响应中接收数据的**模式(schemas)**： |
|||
|
|||
<img src="/img/tutorial/generate-clients/image01.png"> |
|||
|
|||
您可以看到这些模式，因为它们是用程序中的模型声明的。 |
|||
|
|||
那些信息可以在应用的 **OpenAPI模式** 被找到，然后显示在API文档中（通过Swagger UI）。 |
|||
|
|||
OpenAPI中所包含的模型里有相同的信息可以用于 **生成客户端代码**。 |
|||
|
|||
### 生成一个TypeScript 客户端 |
|||
|
|||
现在我们有了带有模型的应用，我们可以为前端生成客户端代码。 |
|||
|
|||
#### 安装 `openapi-typescript-codegen` |
|||
|
|||
您可以使用以下工具在前端代码中安装 `openapi-typescript-codegen`: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ npm install openapi-typescript-codegen --save-dev |
|||
|
|||
---> 100% |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
#### 生成客户端代码 |
|||
|
|||
要生成客户端代码，您可以使用现在将要安装的命令行应用程序 `openapi`。 |
|||
|
|||
因为它安装在本地项目中，所以您可能无法直接使用此命令，但您可以将其放在 `package.json` 文件中。 |
|||
|
|||
它可能看起来是这样的: |
|||
|
|||
```JSON hl_lines="7" |
|||
{ |
|||
"name": "frontend-app", |
|||
"version": "1.0.0", |
|||
"description": "", |
|||
"main": "index.js", |
|||
"scripts": { |
|||
"generate-client": "openapi --input http://localhost:8000/openapi.json --output ./src/client --client axios" |
|||
}, |
|||
"author": "", |
|||
"license": "", |
|||
"devDependencies": { |
|||
"openapi-typescript-codegen": "^0.20.1", |
|||
"typescript": "^4.6.2" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
在这里添加 NPM `generate-client` 脚本后，您可以使用以下命令运行它: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ npm run generate-client |
|||
|
|||
[email protected] generate-client /home/user/code/frontend-app |
|||
> openapi --input http://localhost:8000/openapi.json --output ./src/client --client axios |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
此命令将在 `./src/client` 中生成代码，并将在其内部使用 `axios`（前端HTTP库）。 |
|||
|
|||
### 尝试客户端代码 |
|||
|
|||
现在您可以导入并使用客户端代码，它可能看起来像这样，请注意，您可以为这些方法使用自动补全： |
|||
|
|||
<img src="/img/tutorial/generate-clients/image02.png"> |
|||
|
|||
您还将自动补全要发送的数据： |
|||
|
|||
<img src="/img/tutorial/generate-clients/image03.png"> |
|||
|
|||
!!! tip |
|||
请注意， `name` 和 `price` 的自动补全，是通过其在`Item`模型(FastAPI)中的定义实现的。 |
|||
|
|||
如果发送的数据字段不符，你也会看到编辑器的错误提示: |
|||
|
|||
<img src="/img/tutorial/generate-clients/image04.png"> |
|||
|
|||
响应(response)对象也拥有自动补全: |
|||
|
|||
<img src="/img/tutorial/generate-clients/image05.png"> |
|||
|
|||
## 带有标签的 FastAPI 应用 |
|||
|
|||
在许多情况下，你的FastAPI应用程序会更复杂，你可能会使用标签来分隔不同组的*路径操作(path operations)*。 |
|||
|
|||
例如，您可以有一个用 `items` 的部分和另一个用于 `users` 的部分，它们可以用标签来分隔： |
|||
|
|||
=== "Python 3.9+" |
|||
|
|||
```Python hl_lines="21 26 34" |
|||
{!> ../../../docs_src/generate_clients/tutorial002_py39.py!} |
|||
``` |
|||
|
|||
=== "Python 3.6+" |
|||
|
|||
```Python hl_lines="23 28 36" |
|||
{!> ../../../docs_src/generate_clients/tutorial002.py!} |
|||
``` |
|||
|
|||
### 生成带有标签的 TypeScript 客户端 |
|||
|
|||
如果您使用标签为FastAPI应用生成客户端，它通常也会根据标签分割客户端代码。 |
|||
|
|||
通过这种方式，您将能够为客户端代码进行正确地排序和分组： |
|||
|
|||
<img src="/img/tutorial/generate-clients/image06.png"> |
|||
|
|||
在这个案例中，您有： |
|||
|
|||
* `ItemsService` |
|||
* `UsersService` |
|||
|
|||
### 客户端方法名称 |
|||
|
|||
现在生成的方法名像 `createItemItemsPost` 看起来不太简洁: |
|||
|
|||
```TypeScript |
|||
ItemsService.createItemItemsPost({name: "Plumbus", price: 5}) |
|||
``` |
|||
|
|||
...这是因为客户端生成器为每个 *路径操作* 使用OpenAPI的内部 **操作 ID(operation ID)**。 |
|||
|
|||
OpenAPI要求每个操作 ID 在所有 *路径操作* 中都是唯一的，因此 FastAPI 使用**函数名**、**路径**和**HTTP方法/操作**来生成此操作ID，因为这样可以确保这些操作 ID 是唯一的。 |
|||
|
|||
但接下来我会告诉你如何改进。 🤓 |
|||
|
|||
## 自定义操作ID和更好的方法名 |
|||
|
|||
您可以**修改**这些操作ID的**生成**方式，以使其更简洁，并在客户端中具有**更简洁的方法名称**。 |
|||
|
|||
在这种情况下，您必须确保每个操作ID在其他方面是**唯一**的。 |
|||
|
|||
例如，您可以确保每个*路径操作*都有一个标签，然后根据**标签**和*路径操作***名称**（函数名）来生成操作ID。 |
|||
|
|||
### 自定义生成唯一ID函数 |
|||
|
|||
FastAPI为每个*路径操作*使用一个**唯一ID**，它用于**操作ID**，也用于任何所需自定义模型的名称，用于请求或响应。 |
|||
|
|||
你可以自定义该函数。它接受一个 `APIRoute` 对象作为输入，并输出一个字符串。 |
|||
|
|||
例如，以下是一个示例，它使用第一个标签（你可能只有一个标签）和*路径操作*名称（函数名）。 |
|||
|
|||
然后，你可以将这个自定义函数作为 `generate_unique_id_function` 参数传递给 **FastAPI**: |
|||
|
|||
=== "Python 3.9+" |
|||
|
|||
```Python hl_lines="6-7 10" |
|||
{!> ../../../docs_src/generate_clients/tutorial003_py39.py!} |
|||
``` |
|||
|
|||
=== "Python 3.6+" |
|||
|
|||
```Python hl_lines="8-9 12" |
|||
{!> ../../../docs_src/generate_clients/tutorial003.py!} |
|||
``` |
|||
|
|||
### 使用自定义操作ID生成TypeScript客户端 |
|||
|
|||
现在，如果你再次生成客户端，你会发现它具有改善的方法名称： |
|||
|
|||
<img src="/img/tutorial/generate-clients/image07.png"> |
|||
|
|||
正如你所见，现在方法名称中只包含标签和函数名，不再包含URL路径和HTTP操作的信息。 |
|||
|
|||
### 预处理用于客户端生成器的OpenAPI规范 |
|||
|
|||
生成的代码仍然存在一些**重复的信息**。 |
|||
|
|||
我们已经知道该方法与 **items** 相关，因为它在 `ItemsService` 中（从标签中获取），但方法名中仍然有标签名作为前缀。😕 |
|||
|
|||
一般情况下对于OpenAPI，我们可能仍然希望保留它，因为这将确保操作ID是**唯一的**。 |
|||
|
|||
但对于生成的客户端，我们可以在生成客户端之前**修改** OpenAPI 操作ID，以使方法名称更加美观和**简洁**。 |
|||
|
|||
我们可以将 OpenAPI JSON 下载到一个名为`openapi.json`的文件中，然后使用以下脚本**删除此前缀的标签**： |
|||
|
|||
```Python |
|||
{!../../../docs_src/generate_clients/tutorial004.py!} |
|||
``` |
|||
|
|||
通过这样做，操作ID将从类似于 `items-get_items` 的名称重命名为 `get_items` ，这样客户端生成器就可以生成更简洁的方法名称。 |
|||
|
|||
### 使用预处理的OpenAPI生成TypeScript客户端 |
|||
|
|||
现在，由于最终结果保存在文件openapi.json中，你可以修改 package.json 文件以使用此本地文件，例如： |
|||
|
|||
```JSON hl_lines="7" |
|||
{ |
|||
"name": "frontend-app", |
|||
"version": "1.0.0", |
|||
"description": "", |
|||
"main": "index.js", |
|||
"scripts": { |
|||
"generate-client": "openapi --input ./openapi.json --output ./src/client --client axios" |
|||
}, |
|||
"author": "", |
|||
"license": "", |
|||
"devDependencies": { |
|||
"openapi-typescript-codegen": "^0.20.1", |
|||
"typescript": "^4.6.2" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
生成新的客户端之后，你现在将拥有**清晰的方法名称**，具备**自动补全**、**错误提示**等功能： |
|||
|
|||
<img src="/img/tutorial/generate-clients/image08.png"> |
|||
|
|||
## 优点 |
|||
|
|||
当使用自动生成的客户端时，你将获得以下的自动补全功能： |
|||
|
|||
* 方法。 |
|||
* 请求体中的数据、查询参数等。 |
|||
* 响应数据。 |
|||
|
|||
你还将获得针对所有内容的错误提示。 |
|||
|
|||
每当你更新后端代码并**重新生成**前端代码时，新的*路径操作*将作为方法可用，旧的方法将被删除，并且其他任何更改将反映在生成的代码中。 🤓 |
|||
|
|||
这也意味着如果有任何更改，它将自动**反映**在客户端代码中。如果你**构建**客户端，在使用的数据上存在**不匹配**时，它将报错。 |
|||
|
|||
因此，你将在开发周期的早期**检测到许多错误**，而不必等待错误在生产环境中向最终用户展示，然后尝试调试问题所在。 ✨ |
|||
@ -0,0 +1,51 @@ |
|||
from typing import Union |
|||
|
|||
from fastapi import Body, FastAPI |
|||
from pydantic import BaseModel |
|||
|
|||
app = FastAPI() |
|||
|
|||
|
|||
class Item(BaseModel): |
|||
name: str |
|||
description: Union[str, None] = None |
|||
price: float |
|||
tax: Union[float, None] = None |
|||
|
|||
|
|||
@app.put("/items/{item_id}") |
|||
async def update_item( |
|||
*, |
|||
item_id: int, |
|||
item: Item = Body( |
|||
openapi_examples={ |
|||
"normal": { |
|||
"summary": "A normal example", |
|||
"description": "A **normal** item works correctly.", |
|||
"value": { |
|||
"name": "Foo", |
|||
"description": "A very nice Item", |
|||
"price": 35.4, |
|||
"tax": 3.2, |
|||
}, |
|||
}, |
|||
"converted": { |
|||
"summary": "An example with converted data", |
|||
"description": "FastAPI can convert price `strings` to actual `numbers` automatically", |
|||
"value": { |
|||
"name": "Bar", |
|||
"price": "35.4", |
|||
}, |
|||
}, |
|||
"invalid": { |
|||
"summary": "Invalid data is rejected with an error", |
|||
"value": { |
|||
"name": "Baz", |
|||
"price": "thirty five point four", |
|||
}, |
|||
}, |
|||
}, |
|||
), |
|||
): |
|||
results = {"item_id": item_id, "item": item} |
|||
return results |
|||
@ -0,0 +1,55 @@ |
|||
from typing import Union |
|||
|
|||
from fastapi import Body, FastAPI |
|||
from pydantic import BaseModel |
|||
from typing_extensions import Annotated |
|||
|
|||
app = FastAPI() |
|||
|
|||
|
|||
class Item(BaseModel): |
|||
name: str |
|||
description: Union[str, None] = None |
|||
price: float |
|||
tax: Union[float, None] = None |
|||
|
|||
|
|||
@app.put("/items/{item_id}") |
|||
async def update_item( |
|||
*, |
|||
item_id: int, |
|||
item: Annotated[ |
|||
Item, |
|||
Body( |
|||
openapi_examples={ |
|||
"normal": { |
|||
"summary": "A normal example", |
|||
"description": "A **normal** item works correctly.", |
|||
"value": { |
|||
"name": "Foo", |
|||
"description": "A very nice Item", |
|||
"price": 35.4, |
|||
"tax": 3.2, |
|||
}, |
|||
}, |
|||
"converted": { |
|||
"summary": "An example with converted data", |
|||
"description": "FastAPI can convert price `strings` to actual `numbers` automatically", |
|||
"value": { |
|||
"name": "Bar", |
|||
"price": "35.4", |
|||
}, |
|||
}, |
|||
"invalid": { |
|||
"summary": "Invalid data is rejected with an error", |
|||
"value": { |
|||
"name": "Baz", |
|||
"price": "thirty five point four", |
|||
}, |
|||
}, |
|||
}, |
|||
), |
|||
], |
|||
): |
|||
results = {"item_id": item_id, "item": item} |
|||
return results |
|||
@ -0,0 +1,54 @@ |
|||
from typing import Annotated |
|||
|
|||
from fastapi import Body, FastAPI |
|||
from pydantic import BaseModel |
|||
|
|||
app = FastAPI() |
|||
|
|||
|
|||
class Item(BaseModel): |
|||
name: str |
|||
description: str | None = None |
|||
price: float |
|||
tax: float | None = None |
|||
|
|||
|
|||
@app.put("/items/{item_id}") |
|||
async def update_item( |
|||
*, |
|||
item_id: int, |
|||
item: Annotated[ |
|||
Item, |
|||
Body( |
|||
openapi_examples={ |
|||
"normal": { |
|||
"summary": "A normal example", |
|||
"description": "A **normal** item works correctly.", |
|||
"value": { |
|||
"name": "Foo", |
|||
"description": "A very nice Item", |
|||
"price": 35.4, |
|||
"tax": 3.2, |
|||
}, |
|||
}, |
|||
"converted": { |
|||
"summary": "An example with converted data", |
|||
"description": "FastAPI can convert price `strings` to actual `numbers` automatically", |
|||
"value": { |
|||
"name": "Bar", |
|||
"price": "35.4", |
|||
}, |
|||
}, |
|||
"invalid": { |
|||
"summary": "Invalid data is rejected with an error", |
|||
"value": { |
|||
"name": "Baz", |
|||
"price": "thirty five point four", |
|||
}, |
|||
}, |
|||
}, |
|||
), |
|||
], |
|||
): |
|||
results = {"item_id": item_id, "item": item} |
|||
return results |
|||
@ -0,0 +1,54 @@ |
|||
from typing import Annotated, Union |
|||
|
|||
from fastapi import Body, FastAPI |
|||
from pydantic import BaseModel |
|||
|
|||
app = FastAPI() |
|||
|
|||
|
|||
class Item(BaseModel): |
|||
name: str |
|||
description: Union[str, None] = None |
|||
price: float |
|||
tax: Union[float, None] = None |
|||
|
|||
|
|||
@app.put("/items/{item_id}") |
|||
async def update_item( |
|||
*, |
|||
item_id: int, |
|||
item: Annotated[ |
|||
Item, |
|||
Body( |
|||
openapi_examples={ |
|||
"normal": { |
|||
"summary": "A normal example", |
|||
"description": "A **normal** item works correctly.", |
|||
"value": { |
|||
"name": "Foo", |
|||
"description": "A very nice Item", |
|||
"price": 35.4, |
|||
"tax": 3.2, |
|||
}, |
|||
}, |
|||
"converted": { |
|||
"summary": "An example with converted data", |
|||
"description": "FastAPI can convert price `strings` to actual `numbers` automatically", |
|||
"value": { |
|||
"name": "Bar", |
|||
"price": "35.4", |
|||
}, |
|||
}, |
|||
"invalid": { |
|||
"summary": "Invalid data is rejected with an error", |
|||
"value": { |
|||
"name": "Baz", |
|||
"price": "thirty five point four", |
|||
}, |
|||
}, |
|||
}, |
|||
), |
|||
], |
|||
): |
|||
results = {"item_id": item_id, "item": item} |
|||
return results |
|||
@ -0,0 +1,49 @@ |
|||
from fastapi import Body, FastAPI |
|||
from pydantic import BaseModel |
|||
|
|||
app = FastAPI() |
|||
|
|||
|
|||
class Item(BaseModel): |
|||
name: str |
|||
description: str | None = None |
|||
price: float |
|||
tax: float | None = None |
|||
|
|||
|
|||
@app.put("/items/{item_id}") |
|||
async def update_item( |
|||
*, |
|||
item_id: int, |
|||
item: Item = Body( |
|||
openapi_examples={ |
|||
"normal": { |
|||
"summary": "A normal example", |
|||
"description": "A **normal** item works correctly.", |
|||
"value": { |
|||
"name": "Foo", |
|||
"description": "A very nice Item", |
|||
"price": 35.4, |
|||
"tax": 3.2, |
|||
}, |
|||
}, |
|||
"converted": { |
|||
"summary": "An example with converted data", |
|||
"description": "FastAPI can convert price `strings` to actual `numbers` automatically", |
|||
"value": { |
|||
"name": "Bar", |
|||
"price": "35.4", |
|||
}, |
|||
}, |
|||
"invalid": { |
|||
"summary": "Invalid data is rejected with an error", |
|||
"value": { |
|||
"name": "Baz", |
|||
"price": "thirty five point four", |
|||
}, |
|||
}, |
|||
}, |
|||
), |
|||
): |
|||
results = {"item_id": item_id, "item": item} |
|||
return results |
|||
@ -0,0 +1,28 @@ |
|||
from typing import List, Union |
|||
|
|||
from fastapi import FastAPI |
|||
from pydantic import BaseModel |
|||
|
|||
|
|||
class Item(BaseModel): |
|||
name: str |
|||
description: Union[str, None] = None |
|||
|
|||
|
|||
app = FastAPI() |
|||
|
|||
|
|||
@app.post("/items/") |
|||
def create_item(item: Item): |
|||
return item |
|||
|
|||
|
|||
@app.get("/items/") |
|||
def read_items() -> List[Item]: |
|||
return [ |
|||
Item( |
|||
name="Portal Gun", |
|||
description="Device to travel through the multi-rick-verse", |
|||
), |
|||
Item(name="Plumbus"), |
|||
] |
|||
@ -0,0 +1,26 @@ |
|||
from fastapi import FastAPI |
|||
from pydantic import BaseModel |
|||
|
|||
|
|||
class Item(BaseModel): |
|||
name: str |
|||
description: str | None = None |
|||
|
|||
|
|||
app = FastAPI() |
|||
|
|||
|
|||
@app.post("/items/") |
|||
def create_item(item: Item): |
|||
return item |
|||
|
|||
|
|||
@app.get("/items/") |
|||
def read_items() -> list[Item]: |
|||
return [ |
|||
Item( |
|||
name="Portal Gun", |
|||
description="Device to travel through the multi-rick-verse", |
|||
), |
|||
Item(name="Plumbus"), |
|||
] |
|||
@ -0,0 +1,28 @@ |
|||
from typing import Optional |
|||
|
|||
from fastapi import FastAPI |
|||
from pydantic import BaseModel |
|||
|
|||
|
|||
class Item(BaseModel): |
|||
name: str |
|||
description: Optional[str] = None |
|||
|
|||
|
|||
app = FastAPI() |
|||
|
|||
|
|||
@app.post("/items/") |
|||
def create_item(item: Item): |
|||
return item |
|||
|
|||
|
|||
@app.get("/items/") |
|||
def read_items() -> list[Item]: |
|||
return [ |
|||
Item( |
|||
name="Portal Gun", |
|||
description="Device to travel through the multi-rick-verse", |
|||
), |
|||
Item(name="Plumbus"), |
|||
] |
|||
@ -0,0 +1,28 @@ |
|||
from typing import List, Union |
|||
|
|||
from fastapi import FastAPI |
|||
from pydantic import BaseModel |
|||
|
|||
|
|||
class Item(BaseModel): |
|||
name: str |
|||
description: Union[str, None] = None |
|||
|
|||
|
|||
app = FastAPI(separate_input_output_schemas=False) |
|||
|
|||
|
|||
@app.post("/items/") |
|||
def create_item(item: Item): |
|||
return item |
|||
|
|||
|
|||
@app.get("/items/") |
|||
def read_items() -> List[Item]: |
|||
return [ |
|||
Item( |
|||
name="Portal Gun", |
|||
description="Device to travel through the multi-rick-verse", |
|||
), |
|||
Item(name="Plumbus"), |
|||
] |
|||
@ -0,0 +1,26 @@ |
|||
from fastapi import FastAPI |
|||
from pydantic import BaseModel |
|||
|
|||
|
|||
class Item(BaseModel): |
|||
name: str |
|||
description: str | None = None |
|||
|
|||
|
|||
app = FastAPI(separate_input_output_schemas=False) |
|||
|
|||
|
|||
@app.post("/items/") |
|||
def create_item(item: Item): |
|||
return item |
|||
|
|||
|
|||
@app.get("/items/") |
|||
def read_items() -> list[Item]: |
|||
return [ |
|||
Item( |
|||
name="Portal Gun", |
|||
description="Device to travel through the multi-rick-verse", |
|||
), |
|||
Item(name="Plumbus"), |
|||
] |
|||
@ -0,0 +1,28 @@ |
|||
from typing import Optional |
|||
|
|||
from fastapi import FastAPI |
|||
from pydantic import BaseModel |
|||
|
|||
|
|||
class Item(BaseModel): |
|||
name: str |
|||
description: Optional[str] = None |
|||
|
|||
|
|||
app = FastAPI(separate_input_output_schemas=False) |
|||
|
|||
|
|||
@app.post("/items/") |
|||
def create_item(item: Item): |
|||
return item |
|||
|
|||
|
|||
@app.get("/items/") |
|||
def read_items() -> list[Item]: |
|||
return [ |
|||
Item( |
|||
name="Portal Gun", |
|||
description="Device to travel through the multi-rick-verse", |
|||
), |
|||
Item(name="Plumbus"), |
|||
] |
|||
@ -0,0 +1,29 @@ |
|||
import subprocess |
|||
|
|||
from playwright.sync_api import Playwright, sync_playwright |
|||
|
|||
|
|||
def run(playwright: Playwright) -> None: |
|||
browser = playwright.chromium.launch(headless=False) |
|||
context = browser.new_context(viewport={"width": 960, "height": 1080}) |
|||
page = context.new_page() |
|||
page.goto("http://localhost:8000/docs") |
|||
page.get_by_text("POST/items/Create Item").click() |
|||
page.get_by_role("tab", name="Schema").first.click() |
|||
page.screenshot( |
|||
path="docs/en/docs/img/tutorial/separate-openapi-schemas/image01.png" |
|||
) |
|||
|
|||
# --------------------- |
|||
context.close() |
|||
browser.close() |
|||
|
|||
|
|||
process = subprocess.Popen( |
|||
["uvicorn", "docs_src.separate_openapi_schemas.tutorial001:app"] |
|||
) |
|||
try: |
|||
with sync_playwright() as playwright: |
|||
run(playwright) |
|||
finally: |
|||
process.terminate() |
|||
@ -0,0 +1,30 @@ |
|||
import subprocess |
|||
|
|||
from playwright.sync_api import Playwright, sync_playwright |
|||
|
|||
|
|||
def run(playwright: Playwright) -> None: |
|||
browser = playwright.chromium.launch(headless=False) |
|||
context = browser.new_context(viewport={"width": 960, "height": 1080}) |
|||
page = context.new_page() |
|||
page.goto("http://localhost:8000/docs") |
|||
page.get_by_text("GET/items/Read Items").click() |
|||
page.get_by_role("button", name="Try it out").click() |
|||
page.get_by_role("button", name="Execute").click() |
|||
page.screenshot( |
|||
path="docs/en/docs/img/tutorial/separate-openapi-schemas/image02.png" |
|||
) |
|||
|
|||
# --------------------- |
|||
context.close() |
|||
browser.close() |
|||
|
|||
|
|||
process = subprocess.Popen( |
|||
["uvicorn", "docs_src.separate_openapi_schemas.tutorial001:app"] |
|||
) |
|||
try: |
|||
with sync_playwright() as playwright: |
|||
run(playwright) |
|||
finally: |
|||
process.terminate() |
|||
@ -0,0 +1,30 @@ |
|||
import subprocess |
|||
|
|||
from playwright.sync_api import Playwright, sync_playwright |
|||
|
|||
|
|||
def run(playwright: Playwright) -> None: |
|||
browser = playwright.chromium.launch(headless=False) |
|||
context = browser.new_context(viewport={"width": 960, "height": 1080}) |
|||
page = context.new_page() |
|||
page.goto("http://localhost:8000/docs") |
|||
page.get_by_text("GET/items/Read Items").click() |
|||
page.get_by_role("tab", name="Schema").click() |
|||
page.get_by_label("Schema").get_by_role("button", name="Expand all").click() |
|||
page.screenshot( |
|||
path="docs/en/docs/img/tutorial/separate-openapi-schemas/image03.png" |
|||
) |
|||
|
|||
# --------------------- |
|||
context.close() |
|||
browser.close() |
|||
|
|||
|
|||
process = subprocess.Popen( |
|||
["uvicorn", "docs_src.separate_openapi_schemas.tutorial001:app"] |
|||
) |
|||
try: |
|||
with sync_playwright() as playwright: |
|||
run(playwright) |
|||
finally: |
|||
process.terminate() |
|||
@ -0,0 +1,29 @@ |
|||
import subprocess |
|||
|
|||
from playwright.sync_api import Playwright, sync_playwright |
|||
|
|||
|
|||
def run(playwright: Playwright) -> None: |
|||
browser = playwright.chromium.launch(headless=False) |
|||
context = browser.new_context(viewport={"width": 960, "height": 1080}) |
|||
page = context.new_page() |
|||
page.goto("http://localhost:8000/docs") |
|||
page.get_by_role("button", name="Item-Input").click() |
|||
page.get_by_role("button", name="Item-Output").click() |
|||
page.set_viewport_size({"width": 960, "height": 820}) |
|||
page.screenshot( |
|||
path="docs/en/docs/img/tutorial/separate-openapi-schemas/image04.png" |
|||
) |
|||
# --------------------- |
|||
context.close() |
|||
browser.close() |
|||
|
|||
|
|||
process = subprocess.Popen( |
|||
["uvicorn", "docs_src.separate_openapi_schemas.tutorial001:app"] |
|||
) |
|||
try: |
|||
with sync_playwright() as playwright: |
|||
run(playwright) |
|||
finally: |
|||
process.terminate() |
|||
@ -0,0 +1,29 @@ |
|||
import subprocess |
|||
|
|||
from playwright.sync_api import Playwright, sync_playwright |
|||
|
|||
|
|||
def run(playwright: Playwright) -> None: |
|||
browser = playwright.chromium.launch(headless=False) |
|||
context = browser.new_context(viewport={"width": 960, "height": 1080}) |
|||
page = context.new_page() |
|||
page.goto("http://localhost:8000/docs") |
|||
page.get_by_role("button", name="Item", exact=True).click() |
|||
page.set_viewport_size({"width": 960, "height": 700}) |
|||
page.screenshot( |
|||
path="docs/en/docs/img/tutorial/separate-openapi-schemas/image05.png" |
|||
) |
|||
|
|||
# --------------------- |
|||
context.close() |
|||
browser.close() |
|||
|
|||
|
|||
process = subprocess.Popen( |
|||
["uvicorn", "docs_src.separate_openapi_schemas.tutorial002:app"] |
|||
) |
|||
try: |
|||
with sync_playwright() as playwright: |
|||
run(playwright) |
|||
finally: |
|||
process.terminate() |
|||
@ -0,0 +1,458 @@ |
|||
from typing import Union |
|||
|
|||
from dirty_equals import IsDict |
|||
from fastapi import Body, Cookie, FastAPI, Header, Path, Query |
|||
from fastapi.testclient import TestClient |
|||
from pydantic import BaseModel |
|||
|
|||
app = FastAPI() |
|||
|
|||
|
|||
class Item(BaseModel): |
|||
data: str |
|||
|
|||
|
|||
@app.post("/examples/") |
|||
def examples( |
|||
item: Item = Body( |
|||
examples=[ |
|||
{"data": "Data in Body examples, example1"}, |
|||
], |
|||
openapi_examples={ |
|||
"Example One": { |
|||
"summary": "Example One Summary", |
|||
"description": "Example One Description", |
|||
"value": {"data": "Data in Body examples, example1"}, |
|||
}, |
|||
"Example Two": { |
|||
"value": {"data": "Data in Body examples, example2"}, |
|||
}, |
|||
}, |
|||
) |
|||
): |
|||
return item |
|||
|
|||
|
|||
@app.get("/path_examples/{item_id}") |
|||
def path_examples( |
|||
item_id: str = Path( |
|||
examples=[ |
|||
"json_schema_item_1", |
|||
"json_schema_item_2", |
|||
], |
|||
openapi_examples={ |
|||
"Path One": { |
|||
"summary": "Path One Summary", |
|||
"description": "Path One Description", |
|||
"value": "item_1", |
|||
}, |
|||
"Path Two": { |
|||
"value": "item_2", |
|||
}, |
|||
}, |
|||
), |
|||
): |
|||
return item_id |
|||
|
|||
|
|||
@app.get("/query_examples/") |
|||
def query_examples( |
|||
data: Union[str, None] = Query( |
|||
default=None, |
|||
examples=[ |
|||
"json_schema_query1", |
|||
"json_schema_query2", |
|||
], |
|||
openapi_examples={ |
|||
"Query One": { |
|||
"summary": "Query One Summary", |
|||
"description": "Query One Description", |
|||
"value": "query1", |
|||
}, |
|||
"Query Two": { |
|||
"value": "query2", |
|||
}, |
|||
}, |
|||
), |
|||
): |
|||
return data |
|||
|
|||
|
|||
@app.get("/header_examples/") |
|||
def header_examples( |
|||
data: Union[str, None] = Header( |
|||
default=None, |
|||
examples=[ |
|||
"json_schema_header1", |
|||
"json_schema_header2", |
|||
], |
|||
openapi_examples={ |
|||
"Header One": { |
|||
"summary": "Header One Summary", |
|||
"description": "Header One Description", |
|||
"value": "header1", |
|||
}, |
|||
"Header Two": { |
|||
"value": "header2", |
|||
}, |
|||
}, |
|||
), |
|||
): |
|||
return data |
|||
|
|||
|
|||
@app.get("/cookie_examples/") |
|||
def cookie_examples( |
|||
data: Union[str, None] = Cookie( |
|||
default=None, |
|||
examples=["json_schema_cookie1", "json_schema_cookie2"], |
|||
openapi_examples={ |
|||
"Cookie One": { |
|||
"summary": "Cookie One Summary", |
|||
"description": "Cookie One Description", |
|||
"value": "cookie1", |
|||
}, |
|||
"Cookie Two": { |
|||
"value": "cookie2", |
|||
}, |
|||
}, |
|||
), |
|||
): |
|||
return data |
|||
|
|||
|
|||
client = TestClient(app) |
|||
|
|||
|
|||
def test_call_api(): |
|||
response = client.post("/examples/", json={"data": "example1"}) |
|||
assert response.status_code == 200, response.text |
|||
|
|||
response = client.get("/path_examples/foo") |
|||
assert response.status_code == 200, response.text |
|||
|
|||
response = client.get("/query_examples/") |
|||
assert response.status_code == 200, response.text |
|||
|
|||
response = client.get("/header_examples/") |
|||
assert response.status_code == 200, response.text |
|||
|
|||
response = client.get("/cookie_examples/") |
|||
assert response.status_code == 200, response.text |
|||
|
|||
|
|||
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": { |
|||
"/examples/": { |
|||
"post": { |
|||
"summary": "Examples", |
|||
"operationId": "examples_examples__post", |
|||
"requestBody": { |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"allOf": [{"$ref": "#/components/schemas/Item"}], |
|||
"title": "Item", |
|||
"examples": [ |
|||
{"data": "Data in Body examples, example1"} |
|||
], |
|||
}, |
|||
"examples": { |
|||
"Example One": { |
|||
"summary": "Example One Summary", |
|||
"description": "Example One Description", |
|||
"value": { |
|||
"data": "Data in Body examples, example1" |
|||
}, |
|||
}, |
|||
"Example Two": { |
|||
"value": { |
|||
"data": "Data in Body examples, example2" |
|||
} |
|||
}, |
|||
}, |
|||
} |
|||
}, |
|||
"required": True, |
|||
}, |
|||
"responses": { |
|||
"200": { |
|||
"description": "Successful Response", |
|||
"content": {"application/json": {"schema": {}}}, |
|||
}, |
|||
"422": { |
|||
"description": "Validation Error", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"$ref": "#/components/schemas/HTTPValidationError" |
|||
} |
|||
} |
|||
}, |
|||
}, |
|||
}, |
|||
} |
|||
}, |
|||
"/path_examples/{item_id}": { |
|||
"get": { |
|||
"summary": "Path Examples", |
|||
"operationId": "path_examples_path_examples__item_id__get", |
|||
"parameters": [ |
|||
{ |
|||
"name": "item_id", |
|||
"in": "path", |
|||
"required": True, |
|||
"schema": { |
|||
"type": "string", |
|||
"examples": [ |
|||
"json_schema_item_1", |
|||
"json_schema_item_2", |
|||
], |
|||
"title": "Item Id", |
|||
}, |
|||
"examples": { |
|||
"Path One": { |
|||
"summary": "Path One Summary", |
|||
"description": "Path One Description", |
|||
"value": "item_1", |
|||
}, |
|||
"Path Two": {"value": "item_2"}, |
|||
}, |
|||
} |
|||
], |
|||
"responses": { |
|||
"200": { |
|||
"description": "Successful Response", |
|||
"content": {"application/json": {"schema": {}}}, |
|||
}, |
|||
"422": { |
|||
"description": "Validation Error", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"$ref": "#/components/schemas/HTTPValidationError" |
|||
} |
|||
} |
|||
}, |
|||
}, |
|||
}, |
|||
} |
|||
}, |
|||
"/query_examples/": { |
|||
"get": { |
|||
"summary": "Query Examples", |
|||
"operationId": "query_examples_query_examples__get", |
|||
"parameters": [ |
|||
{ |
|||
"name": "data", |
|||
"in": "query", |
|||
"required": False, |
|||
"schema": IsDict( |
|||
{ |
|||
"anyOf": [{"type": "string"}, {"type": "null"}], |
|||
"examples": [ |
|||
"json_schema_query1", |
|||
"json_schema_query2", |
|||
], |
|||
"title": "Data", |
|||
} |
|||
) |
|||
| IsDict( |
|||
# TODO: remove when deprecating Pydantic v1 |
|||
{ |
|||
"examples": [ |
|||
"json_schema_query1", |
|||
"json_schema_query2", |
|||
], |
|||
"type": "string", |
|||
"title": "Data", |
|||
} |
|||
), |
|||
"examples": { |
|||
"Query One": { |
|||
"summary": "Query One Summary", |
|||
"description": "Query One Description", |
|||
"value": "query1", |
|||
}, |
|||
"Query Two": {"value": "query2"}, |
|||
}, |
|||
} |
|||
], |
|||
"responses": { |
|||
"200": { |
|||
"description": "Successful Response", |
|||
"content": {"application/json": {"schema": {}}}, |
|||
}, |
|||
"422": { |
|||
"description": "Validation Error", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"$ref": "#/components/schemas/HTTPValidationError" |
|||
} |
|||
} |
|||
}, |
|||
}, |
|||
}, |
|||
} |
|||
}, |
|||
"/header_examples/": { |
|||
"get": { |
|||
"summary": "Header Examples", |
|||
"operationId": "header_examples_header_examples__get", |
|||
"parameters": [ |
|||
{ |
|||
"name": "data", |
|||
"in": "header", |
|||
"required": False, |
|||
"schema": IsDict( |
|||
{ |
|||
"anyOf": [{"type": "string"}, {"type": "null"}], |
|||
"examples": [ |
|||
"json_schema_header1", |
|||
"json_schema_header2", |
|||
], |
|||
"title": "Data", |
|||
} |
|||
) |
|||
| IsDict( |
|||
# TODO: remove when deprecating Pydantic v1 |
|||
{ |
|||
"type": "string", |
|||
"examples": [ |
|||
"json_schema_header1", |
|||
"json_schema_header2", |
|||
], |
|||
"title": "Data", |
|||
} |
|||
), |
|||
"examples": { |
|||
"Header One": { |
|||
"summary": "Header One Summary", |
|||
"description": "Header One Description", |
|||
"value": "header1", |
|||
}, |
|||
"Header Two": {"value": "header2"}, |
|||
}, |
|||
} |
|||
], |
|||
"responses": { |
|||
"200": { |
|||
"description": "Successful Response", |
|||
"content": {"application/json": {"schema": {}}}, |
|||
}, |
|||
"422": { |
|||
"description": "Validation Error", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"$ref": "#/components/schemas/HTTPValidationError" |
|||
} |
|||
} |
|||
}, |
|||
}, |
|||
}, |
|||
} |
|||
}, |
|||
"/cookie_examples/": { |
|||
"get": { |
|||
"summary": "Cookie Examples", |
|||
"operationId": "cookie_examples_cookie_examples__get", |
|||
"parameters": [ |
|||
{ |
|||
"name": "data", |
|||
"in": "cookie", |
|||
"required": False, |
|||
"schema": IsDict( |
|||
{ |
|||
"anyOf": [{"type": "string"}, {"type": "null"}], |
|||
"examples": [ |
|||
"json_schema_cookie1", |
|||
"json_schema_cookie2", |
|||
], |
|||
"title": "Data", |
|||
} |
|||
) |
|||
| IsDict( |
|||
# TODO: remove when deprecating Pydantic v1 |
|||
{ |
|||
"type": "string", |
|||
"examples": [ |
|||
"json_schema_cookie1", |
|||
"json_schema_cookie2", |
|||
], |
|||
"title": "Data", |
|||
} |
|||
), |
|||
"examples": { |
|||
"Cookie One": { |
|||
"summary": "Cookie One Summary", |
|||
"description": "Cookie One Description", |
|||
"value": "cookie1", |
|||
}, |
|||
"Cookie Two": {"value": "cookie2"}, |
|||
}, |
|||
} |
|||
], |
|||
"responses": { |
|||
"200": { |
|||
"description": "Successful Response", |
|||
"content": {"application/json": {"schema": {}}}, |
|||
}, |
|||
"422": { |
|||
"description": "Validation Error", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"$ref": "#/components/schemas/HTTPValidationError" |
|||
} |
|||
} |
|||
}, |
|||
}, |
|||
}, |
|||
} |
|||
}, |
|||
}, |
|||
"components": { |
|||
"schemas": { |
|||
"HTTPValidationError": { |
|||
"properties": { |
|||
"detail": { |
|||
"items": {"$ref": "#/components/schemas/ValidationError"}, |
|||
"type": "array", |
|||
"title": "Detail", |
|||
} |
|||
}, |
|||
"type": "object", |
|||
"title": "HTTPValidationError", |
|||
}, |
|||
"Item": { |
|||
"properties": {"data": {"type": "string", "title": "Data"}}, |
|||
"type": "object", |
|||
"required": ["data"], |
|||
"title": "Item", |
|||
}, |
|||
"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", |
|||
}, |
|||
} |
|||
}, |
|||
} |
|||
@ -0,0 +1,490 @@ |
|||
from typing import List, Optional |
|||
|
|||
from fastapi import FastAPI |
|||
from fastapi.testclient import TestClient |
|||
from pydantic import BaseModel |
|||
|
|||
from .utils import needs_pydanticv2 |
|||
|
|||
|
|||
class SubItem(BaseModel): |
|||
subname: str |
|||
sub_description: Optional[str] = None |
|||
tags: List[str] = [] |
|||
|
|||
|
|||
class Item(BaseModel): |
|||
name: str |
|||
description: Optional[str] = None |
|||
sub: Optional[SubItem] = None |
|||
|
|||
|
|||
def get_app_client(separate_input_output_schemas: bool = True) -> TestClient: |
|||
app = FastAPI(separate_input_output_schemas=separate_input_output_schemas) |
|||
|
|||
@app.post("/items/") |
|||
def create_item(item: Item): |
|||
return item |
|||
|
|||
@app.post("/items-list/") |
|||
def create_item_list(item: List[Item]): |
|||
return item |
|||
|
|||
@app.get("/items/") |
|||
def read_items() -> List[Item]: |
|||
return [ |
|||
Item( |
|||
name="Portal Gun", |
|||
description="Device to travel through the multi-rick-verse", |
|||
sub=SubItem(subname="subname"), |
|||
), |
|||
Item(name="Plumbus"), |
|||
] |
|||
|
|||
client = TestClient(app) |
|||
return client |
|||
|
|||
|
|||
def test_create_item(): |
|||
client = get_app_client() |
|||
client_no = get_app_client(separate_input_output_schemas=False) |
|||
response = client.post("/items/", json={"name": "Plumbus"}) |
|||
response2 = client_no.post("/items/", json={"name": "Plumbus"}) |
|||
assert response.status_code == response2.status_code == 200, response.text |
|||
assert ( |
|||
response.json() |
|||
== response2.json() |
|||
== {"name": "Plumbus", "description": None, "sub": None} |
|||
) |
|||
|
|||
|
|||
def test_create_item_with_sub(): |
|||
client = get_app_client() |
|||
client_no = get_app_client(separate_input_output_schemas=False) |
|||
data = { |
|||
"name": "Plumbus", |
|||
"sub": {"subname": "SubPlumbus", "sub_description": "Sub WTF"}, |
|||
} |
|||
response = client.post("/items/", json=data) |
|||
response2 = client_no.post("/items/", json=data) |
|||
assert response.status_code == response2.status_code == 200, response.text |
|||
assert ( |
|||
response.json() |
|||
== response2.json() |
|||
== { |
|||
"name": "Plumbus", |
|||
"description": None, |
|||
"sub": {"subname": "SubPlumbus", "sub_description": "Sub WTF", "tags": []}, |
|||
} |
|||
) |
|||
|
|||
|
|||
def test_create_item_list(): |
|||
client = get_app_client() |
|||
client_no = get_app_client(separate_input_output_schemas=False) |
|||
data = [ |
|||
{"name": "Plumbus"}, |
|||
{ |
|||
"name": "Portal Gun", |
|||
"description": "Device to travel through the multi-rick-verse", |
|||
}, |
|||
] |
|||
response = client.post("/items-list/", json=data) |
|||
response2 = client_no.post("/items-list/", json=data) |
|||
assert response.status_code == response2.status_code == 200, response.text |
|||
assert ( |
|||
response.json() |
|||
== response2.json() |
|||
== [ |
|||
{"name": "Plumbus", "description": None, "sub": None}, |
|||
{ |
|||
"name": "Portal Gun", |
|||
"description": "Device to travel through the multi-rick-verse", |
|||
"sub": None, |
|||
}, |
|||
] |
|||
) |
|||
|
|||
|
|||
def test_read_items(): |
|||
client = get_app_client() |
|||
client_no = get_app_client(separate_input_output_schemas=False) |
|||
response = client.get("/items/") |
|||
response2 = client_no.get("/items/") |
|||
assert response.status_code == response2.status_code == 200, response.text |
|||
assert ( |
|||
response.json() |
|||
== response2.json() |
|||
== [ |
|||
{ |
|||
"name": "Portal Gun", |
|||
"description": "Device to travel through the multi-rick-verse", |
|||
"sub": {"subname": "subname", "sub_description": None, "tags": []}, |
|||
}, |
|||
{"name": "Plumbus", "description": None, "sub": None}, |
|||
] |
|||
) |
|||
|
|||
|
|||
@needs_pydanticv2 |
|||
def test_openapi_schema(): |
|||
client = get_app_client() |
|||
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": { |
|||
"/items/": { |
|||
"get": { |
|||
"summary": "Read Items", |
|||
"operationId": "read_items_items__get", |
|||
"responses": { |
|||
"200": { |
|||
"description": "Successful Response", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"items": { |
|||
"$ref": "#/components/schemas/Item-Output" |
|||
}, |
|||
"type": "array", |
|||
"title": "Response Read Items Items Get", |
|||
} |
|||
} |
|||
}, |
|||
} |
|||
}, |
|||
}, |
|||
"post": { |
|||
"summary": "Create Item", |
|||
"operationId": "create_item_items__post", |
|||
"requestBody": { |
|||
"content": { |
|||
"application/json": { |
|||
"schema": {"$ref": "#/components/schemas/Item-Input"} |
|||
} |
|||
}, |
|||
"required": True, |
|||
}, |
|||
"responses": { |
|||
"200": { |
|||
"description": "Successful Response", |
|||
"content": {"application/json": {"schema": {}}}, |
|||
}, |
|||
"422": { |
|||
"description": "Validation Error", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"$ref": "#/components/schemas/HTTPValidationError" |
|||
} |
|||
} |
|||
}, |
|||
}, |
|||
}, |
|||
}, |
|||
}, |
|||
"/items-list/": { |
|||
"post": { |
|||
"summary": "Create Item List", |
|||
"operationId": "create_item_list_items_list__post", |
|||
"requestBody": { |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"items": { |
|||
"$ref": "#/components/schemas/Item-Input" |
|||
}, |
|||
"type": "array", |
|||
"title": "Item", |
|||
} |
|||
} |
|||
}, |
|||
"required": True, |
|||
}, |
|||
"responses": { |
|||
"200": { |
|||
"description": "Successful Response", |
|||
"content": {"application/json": {"schema": {}}}, |
|||
}, |
|||
"422": { |
|||
"description": "Validation Error", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"$ref": "#/components/schemas/HTTPValidationError" |
|||
} |
|||
} |
|||
}, |
|||
}, |
|||
}, |
|||
} |
|||
}, |
|||
}, |
|||
"components": { |
|||
"schemas": { |
|||
"HTTPValidationError": { |
|||
"properties": { |
|||
"detail": { |
|||
"items": {"$ref": "#/components/schemas/ValidationError"}, |
|||
"type": "array", |
|||
"title": "Detail", |
|||
} |
|||
}, |
|||
"type": "object", |
|||
"title": "HTTPValidationError", |
|||
}, |
|||
"Item-Input": { |
|||
"properties": { |
|||
"name": {"type": "string", "title": "Name"}, |
|||
"description": { |
|||
"anyOf": [{"type": "string"}, {"type": "null"}], |
|||
"title": "Description", |
|||
}, |
|||
"sub": { |
|||
"anyOf": [ |
|||
{"$ref": "#/components/schemas/SubItem-Input"}, |
|||
{"type": "null"}, |
|||
] |
|||
}, |
|||
}, |
|||
"type": "object", |
|||
"required": ["name"], |
|||
"title": "Item", |
|||
}, |
|||
"Item-Output": { |
|||
"properties": { |
|||
"name": {"type": "string", "title": "Name"}, |
|||
"description": { |
|||
"anyOf": [{"type": "string"}, {"type": "null"}], |
|||
"title": "Description", |
|||
}, |
|||
"sub": { |
|||
"anyOf": [ |
|||
{"$ref": "#/components/schemas/SubItem-Output"}, |
|||
{"type": "null"}, |
|||
] |
|||
}, |
|||
}, |
|||
"type": "object", |
|||
"required": ["name", "description", "sub"], |
|||
"title": "Item", |
|||
}, |
|||
"SubItem-Input": { |
|||
"properties": { |
|||
"subname": {"type": "string", "title": "Subname"}, |
|||
"sub_description": { |
|||
"anyOf": [{"type": "string"}, {"type": "null"}], |
|||
"title": "Sub Description", |
|||
}, |
|||
"tags": { |
|||
"items": {"type": "string"}, |
|||
"type": "array", |
|||
"title": "Tags", |
|||
"default": [], |
|||
}, |
|||
}, |
|||
"type": "object", |
|||
"required": ["subname"], |
|||
"title": "SubItem", |
|||
}, |
|||
"SubItem-Output": { |
|||
"properties": { |
|||
"subname": {"type": "string", "title": "Subname"}, |
|||
"sub_description": { |
|||
"anyOf": [{"type": "string"}, {"type": "null"}], |
|||
"title": "Sub Description", |
|||
}, |
|||
"tags": { |
|||
"items": {"type": "string"}, |
|||
"type": "array", |
|||
"title": "Tags", |
|||
"default": [], |
|||
}, |
|||
}, |
|||
"type": "object", |
|||
"required": ["subname", "sub_description", "tags"], |
|||
"title": "SubItem", |
|||
}, |
|||
"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", |
|||
}, |
|||
} |
|||
}, |
|||
} |
|||
|
|||
|
|||
@needs_pydanticv2 |
|||
def test_openapi_schema_no_separate(): |
|||
client = get_app_client(separate_input_output_schemas=False) |
|||
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": { |
|||
"/items/": { |
|||
"get": { |
|||
"summary": "Read Items", |
|||
"operationId": "read_items_items__get", |
|||
"responses": { |
|||
"200": { |
|||
"description": "Successful Response", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"items": {"$ref": "#/components/schemas/Item"}, |
|||
"type": "array", |
|||
"title": "Response Read Items Items Get", |
|||
} |
|||
} |
|||
}, |
|||
} |
|||
}, |
|||
}, |
|||
"post": { |
|||
"summary": "Create Item", |
|||
"operationId": "create_item_items__post", |
|||
"requestBody": { |
|||
"content": { |
|||
"application/json": { |
|||
"schema": {"$ref": "#/components/schemas/Item"} |
|||
} |
|||
}, |
|||
"required": True, |
|||
}, |
|||
"responses": { |
|||
"200": { |
|||
"description": "Successful Response", |
|||
"content": {"application/json": {"schema": {}}}, |
|||
}, |
|||
"422": { |
|||
"description": "Validation Error", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"$ref": "#/components/schemas/HTTPValidationError" |
|||
} |
|||
} |
|||
}, |
|||
}, |
|||
}, |
|||
}, |
|||
}, |
|||
"/items-list/": { |
|||
"post": { |
|||
"summary": "Create Item List", |
|||
"operationId": "create_item_list_items_list__post", |
|||
"requestBody": { |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"items": {"$ref": "#/components/schemas/Item"}, |
|||
"type": "array", |
|||
"title": "Item", |
|||
} |
|||
} |
|||
}, |
|||
"required": True, |
|||
}, |
|||
"responses": { |
|||
"200": { |
|||
"description": "Successful Response", |
|||
"content": {"application/json": {"schema": {}}}, |
|||
}, |
|||
"422": { |
|||
"description": "Validation Error", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"$ref": "#/components/schemas/HTTPValidationError" |
|||
} |
|||
} |
|||
}, |
|||
}, |
|||
}, |
|||
} |
|||
}, |
|||
}, |
|||
"components": { |
|||
"schemas": { |
|||
"HTTPValidationError": { |
|||
"properties": { |
|||
"detail": { |
|||
"items": {"$ref": "#/components/schemas/ValidationError"}, |
|||
"type": "array", |
|||
"title": "Detail", |
|||
} |
|||
}, |
|||
"type": "object", |
|||
"title": "HTTPValidationError", |
|||
}, |
|||
"Item": { |
|||
"properties": { |
|||
"name": {"type": "string", "title": "Name"}, |
|||
"description": { |
|||
"anyOf": [{"type": "string"}, {"type": "null"}], |
|||
"title": "Description", |
|||
}, |
|||
"sub": { |
|||
"anyOf": [ |
|||
{"$ref": "#/components/schemas/SubItem"}, |
|||
{"type": "null"}, |
|||
] |
|||
}, |
|||
}, |
|||
"type": "object", |
|||
"required": ["name"], |
|||
"title": "Item", |
|||
}, |
|||
"SubItem": { |
|||
"properties": { |
|||
"subname": {"type": "string", "title": "Subname"}, |
|||
"sub_description": { |
|||
"anyOf": [{"type": "string"}, {"type": "null"}], |
|||
"title": "Sub Description", |
|||
}, |
|||
"tags": { |
|||
"items": {"type": "string"}, |
|||
"type": "array", |
|||
"title": "Tags", |
|||
"default": [], |
|||
}, |
|||
}, |
|||
"type": "object", |
|||
"required": ["subname"], |
|||
"title": "SubItem", |
|||
}, |
|||
"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", |
|||
}, |
|||
} |
|||
}, |
|||
} |
|||
@ -0,0 +1,166 @@ |
|||
import pytest |
|||
from dirty_equals import IsDict |
|||
from fastapi.testclient import TestClient |
|||
|
|||
|
|||
@pytest.fixture(name="client") |
|||
def get_client(): |
|||
from docs_src.schema_extra_example.tutorial005 import app |
|||
|
|||
client = TestClient(app) |
|||
return client |
|||
|
|||
|
|||
def test_post_body_example(client: TestClient): |
|||
response = client.put( |
|||
"/items/5", |
|||
json={ |
|||
"name": "Foo", |
|||
"description": "A very nice Item", |
|||
"price": 35.4, |
|||
"tax": 3.2, |
|||
}, |
|||
) |
|||
assert response.status_code == 200 |
|||
|
|||
|
|||
def test_openapi_schema(client: TestClient) -> None: |
|||
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": { |
|||
"/items/{item_id}": { |
|||
"put": { |
|||
"summary": "Update Item", |
|||
"operationId": "update_item_items__item_id__put", |
|||
"parameters": [ |
|||
{ |
|||
"required": True, |
|||
"schema": {"title": "Item Id", "type": "integer"}, |
|||
"name": "item_id", |
|||
"in": "path", |
|||
} |
|||
], |
|||
"requestBody": { |
|||
"content": { |
|||
"application/json": { |
|||
"schema": IsDict({"$ref": "#/components/schemas/Item"}) |
|||
| IsDict( |
|||
# TODO: remove when deprecating Pydantic v1 |
|||
{ |
|||
"allOf": [ |
|||
{"$ref": "#/components/schemas/Item"} |
|||
], |
|||
"title": "Item", |
|||
} |
|||
), |
|||
"examples": { |
|||
"normal": { |
|||
"summary": "A normal example", |
|||
"description": "A **normal** item works correctly.", |
|||
"value": { |
|||
"name": "Foo", |
|||
"description": "A very nice Item", |
|||
"price": 35.4, |
|||
"tax": 3.2, |
|||
}, |
|||
}, |
|||
"converted": { |
|||
"summary": "An example with converted data", |
|||
"description": "FastAPI can convert price `strings` to actual `numbers` automatically", |
|||
"value": {"name": "Bar", "price": "35.4"}, |
|||
}, |
|||
"invalid": { |
|||
"summary": "Invalid data is rejected with an error", |
|||
"value": { |
|||
"name": "Baz", |
|||
"price": "thirty five point four", |
|||
}, |
|||
}, |
|||
}, |
|||
} |
|||
}, |
|||
"required": True, |
|||
}, |
|||
"responses": { |
|||
"200": { |
|||
"description": "Successful Response", |
|||
"content": {"application/json": {"schema": {}}}, |
|||
}, |
|||
"422": { |
|||
"description": "Validation Error", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"$ref": "#/components/schemas/HTTPValidationError" |
|||
} |
|||
} |
|||
}, |
|||
}, |
|||
}, |
|||
} |
|||
} |
|||
}, |
|||
"components": { |
|||
"schemas": { |
|||
"HTTPValidationError": { |
|||
"title": "HTTPValidationError", |
|||
"type": "object", |
|||
"properties": { |
|||
"detail": { |
|||
"title": "Detail", |
|||
"type": "array", |
|||
"items": {"$ref": "#/components/schemas/ValidationError"}, |
|||
} |
|||
}, |
|||
}, |
|||
"Item": { |
|||
"title": "Item", |
|||
"required": ["name", "price"], |
|||
"type": "object", |
|||
"properties": { |
|||
"name": {"title": "Name", "type": "string"}, |
|||
"description": IsDict( |
|||
{ |
|||
"title": "Description", |
|||
"anyOf": [{"type": "string"}, {"type": "null"}], |
|||
} |
|||
) |
|||
| IsDict( |
|||
# TODO: remove when deprecating Pydantic v1 |
|||
{"title": "Description", "type": "string"} |
|||
), |
|||
"price": {"title": "Price", "type": "number"}, |
|||
"tax": IsDict( |
|||
{ |
|||
"title": "Tax", |
|||
"anyOf": [{"type": "number"}, {"type": "null"}], |
|||
} |
|||
) |
|||
| IsDict( |
|||
# TODO: remove when deprecating Pydantic v1 |
|||
{"title": "Tax", "type": "number"} |
|||
), |
|||
}, |
|||
}, |
|||
"ValidationError": { |
|||
"title": "ValidationError", |
|||
"required": ["loc", "msg", "type"], |
|||
"type": "object", |
|||
"properties": { |
|||
"loc": { |
|||
"title": "Location", |
|||
"type": "array", |
|||
"items": { |
|||
"anyOf": [{"type": "string"}, {"type": "integer"}] |
|||
}, |
|||
}, |
|||
"msg": {"title": "Message", "type": "string"}, |
|||
"type": {"title": "Error Type", "type": "string"}, |
|||
}, |
|||
}, |
|||
} |
|||
}, |
|||
} |
|||
@ -0,0 +1,166 @@ |
|||
import pytest |
|||
from dirty_equals import IsDict |
|||
from fastapi.testclient import TestClient |
|||
|
|||
|
|||
@pytest.fixture(name="client") |
|||
def get_client(): |
|||
from docs_src.schema_extra_example.tutorial005_an import app |
|||
|
|||
client = TestClient(app) |
|||
return client |
|||
|
|||
|
|||
def test_post_body_example(client: TestClient): |
|||
response = client.put( |
|||
"/items/5", |
|||
json={ |
|||
"name": "Foo", |
|||
"description": "A very nice Item", |
|||
"price": 35.4, |
|||
"tax": 3.2, |
|||
}, |
|||
) |
|||
assert response.status_code == 200 |
|||
|
|||
|
|||
def test_openapi_schema(client: TestClient) -> None: |
|||
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": { |
|||
"/items/{item_id}": { |
|||
"put": { |
|||
"summary": "Update Item", |
|||
"operationId": "update_item_items__item_id__put", |
|||
"parameters": [ |
|||
{ |
|||
"required": True, |
|||
"schema": {"title": "Item Id", "type": "integer"}, |
|||
"name": "item_id", |
|||
"in": "path", |
|||
} |
|||
], |
|||
"requestBody": { |
|||
"content": { |
|||
"application/json": { |
|||
"schema": IsDict({"$ref": "#/components/schemas/Item"}) |
|||
| IsDict( |
|||
# TODO: remove when deprecating Pydantic v1 |
|||
{ |
|||
"allOf": [ |
|||
{"$ref": "#/components/schemas/Item"} |
|||
], |
|||
"title": "Item", |
|||
} |
|||
), |
|||
"examples": { |
|||
"normal": { |
|||
"summary": "A normal example", |
|||
"description": "A **normal** item works correctly.", |
|||
"value": { |
|||
"name": "Foo", |
|||
"description": "A very nice Item", |
|||
"price": 35.4, |
|||
"tax": 3.2, |
|||
}, |
|||
}, |
|||
"converted": { |
|||
"summary": "An example with converted data", |
|||
"description": "FastAPI can convert price `strings` to actual `numbers` automatically", |
|||
"value": {"name": "Bar", "price": "35.4"}, |
|||
}, |
|||
"invalid": { |
|||
"summary": "Invalid data is rejected with an error", |
|||
"value": { |
|||
"name": "Baz", |
|||
"price": "thirty five point four", |
|||
}, |
|||
}, |
|||
}, |
|||
} |
|||
}, |
|||
"required": True, |
|||
}, |
|||
"responses": { |
|||
"200": { |
|||
"description": "Successful Response", |
|||
"content": {"application/json": {"schema": {}}}, |
|||
}, |
|||
"422": { |
|||
"description": "Validation Error", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"$ref": "#/components/schemas/HTTPValidationError" |
|||
} |
|||
} |
|||
}, |
|||
}, |
|||
}, |
|||
} |
|||
} |
|||
}, |
|||
"components": { |
|||
"schemas": { |
|||
"HTTPValidationError": { |
|||
"title": "HTTPValidationError", |
|||
"type": "object", |
|||
"properties": { |
|||
"detail": { |
|||
"title": "Detail", |
|||
"type": "array", |
|||
"items": {"$ref": "#/components/schemas/ValidationError"}, |
|||
} |
|||
}, |
|||
}, |
|||
"Item": { |
|||
"title": "Item", |
|||
"required": ["name", "price"], |
|||
"type": "object", |
|||
"properties": { |
|||
"name": {"title": "Name", "type": "string"}, |
|||
"description": IsDict( |
|||
{ |
|||
"title": "Description", |
|||
"anyOf": [{"type": "string"}, {"type": "null"}], |
|||
} |
|||
) |
|||
| IsDict( |
|||
# TODO: remove when deprecating Pydantic v1 |
|||
{"title": "Description", "type": "string"} |
|||
), |
|||
"price": {"title": "Price", "type": "number"}, |
|||
"tax": IsDict( |
|||
{ |
|||
"title": "Tax", |
|||
"anyOf": [{"type": "number"}, {"type": "null"}], |
|||
} |
|||
) |
|||
| IsDict( |
|||
# TODO: remove when deprecating Pydantic v1 |
|||
{"title": "Tax", "type": "number"} |
|||
), |
|||
}, |
|||
}, |
|||
"ValidationError": { |
|||
"title": "ValidationError", |
|||
"required": ["loc", "msg", "type"], |
|||
"type": "object", |
|||
"properties": { |
|||
"loc": { |
|||
"title": "Location", |
|||
"type": "array", |
|||
"items": { |
|||
"anyOf": [{"type": "string"}, {"type": "integer"}] |
|||
}, |
|||
}, |
|||
"msg": {"title": "Message", "type": "string"}, |
|||
"type": {"title": "Error Type", "type": "string"}, |
|||
}, |
|||
}, |
|||
} |
|||
}, |
|||
} |
|||
@ -0,0 +1,170 @@ |
|||
import pytest |
|||
from dirty_equals import IsDict |
|||
from fastapi.testclient import TestClient |
|||
|
|||
from ...utils import needs_py310 |
|||
|
|||
|
|||
@pytest.fixture(name="client") |
|||
def get_client(): |
|||
from docs_src.schema_extra_example.tutorial005_an_py310 import app |
|||
|
|||
client = TestClient(app) |
|||
return client |
|||
|
|||
|
|||
@needs_py310 |
|||
def test_post_body_example(client: TestClient): |
|||
response = client.put( |
|||
"/items/5", |
|||
json={ |
|||
"name": "Foo", |
|||
"description": "A very nice Item", |
|||
"price": 35.4, |
|||
"tax": 3.2, |
|||
}, |
|||
) |
|||
assert response.status_code == 200 |
|||
|
|||
|
|||
@needs_py310 |
|||
def test_openapi_schema(client: TestClient) -> None: |
|||
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": { |
|||
"/items/{item_id}": { |
|||
"put": { |
|||
"summary": "Update Item", |
|||
"operationId": "update_item_items__item_id__put", |
|||
"parameters": [ |
|||
{ |
|||
"required": True, |
|||
"schema": {"title": "Item Id", "type": "integer"}, |
|||
"name": "item_id", |
|||
"in": "path", |
|||
} |
|||
], |
|||
"requestBody": { |
|||
"content": { |
|||
"application/json": { |
|||
"schema": IsDict({"$ref": "#/components/schemas/Item"}) |
|||
| IsDict( |
|||
# TODO: remove when deprecating Pydantic v1 |
|||
{ |
|||
"allOf": [ |
|||
{"$ref": "#/components/schemas/Item"} |
|||
], |
|||
"title": "Item", |
|||
} |
|||
), |
|||
"examples": { |
|||
"normal": { |
|||
"summary": "A normal example", |
|||
"description": "A **normal** item works correctly.", |
|||
"value": { |
|||
"name": "Foo", |
|||
"description": "A very nice Item", |
|||
"price": 35.4, |
|||
"tax": 3.2, |
|||
}, |
|||
}, |
|||
"converted": { |
|||
"summary": "An example with converted data", |
|||
"description": "FastAPI can convert price `strings` to actual `numbers` automatically", |
|||
"value": {"name": "Bar", "price": "35.4"}, |
|||
}, |
|||
"invalid": { |
|||
"summary": "Invalid data is rejected with an error", |
|||
"value": { |
|||
"name": "Baz", |
|||
"price": "thirty five point four", |
|||
}, |
|||
}, |
|||
}, |
|||
} |
|||
}, |
|||
"required": True, |
|||
}, |
|||
"responses": { |
|||
"200": { |
|||
"description": "Successful Response", |
|||
"content": {"application/json": {"schema": {}}}, |
|||
}, |
|||
"422": { |
|||
"description": "Validation Error", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"$ref": "#/components/schemas/HTTPValidationError" |
|||
} |
|||
} |
|||
}, |
|||
}, |
|||
}, |
|||
} |
|||
} |
|||
}, |
|||
"components": { |
|||
"schemas": { |
|||
"HTTPValidationError": { |
|||
"title": "HTTPValidationError", |
|||
"type": "object", |
|||
"properties": { |
|||
"detail": { |
|||
"title": "Detail", |
|||
"type": "array", |
|||
"items": {"$ref": "#/components/schemas/ValidationError"}, |
|||
} |
|||
}, |
|||
}, |
|||
"Item": { |
|||
"title": "Item", |
|||
"required": ["name", "price"], |
|||
"type": "object", |
|||
"properties": { |
|||
"name": {"title": "Name", "type": "string"}, |
|||
"description": IsDict( |
|||
{ |
|||
"title": "Description", |
|||
"anyOf": [{"type": "string"}, {"type": "null"}], |
|||
} |
|||
) |
|||
| IsDict( |
|||
# TODO: remove when deprecating Pydantic v1 |
|||
{"title": "Description", "type": "string"} |
|||
), |
|||
"price": {"title": "Price", "type": "number"}, |
|||
"tax": IsDict( |
|||
{ |
|||
"title": "Tax", |
|||
"anyOf": [{"type": "number"}, {"type": "null"}], |
|||
} |
|||
) |
|||
| IsDict( |
|||
# TODO: remove when deprecating Pydantic v1 |
|||
{"title": "Tax", "type": "number"} |
|||
), |
|||
}, |
|||
}, |
|||
"ValidationError": { |
|||
"title": "ValidationError", |
|||
"required": ["loc", "msg", "type"], |
|||
"type": "object", |
|||
"properties": { |
|||
"loc": { |
|||
"title": "Location", |
|||
"type": "array", |
|||
"items": { |
|||
"anyOf": [{"type": "string"}, {"type": "integer"}] |
|||
}, |
|||
}, |
|||
"msg": {"title": "Message", "type": "string"}, |
|||
"type": {"title": "Error Type", "type": "string"}, |
|||
}, |
|||
}, |
|||
} |
|||
}, |
|||
} |
|||
@ -0,0 +1,170 @@ |
|||
import pytest |
|||
from dirty_equals import IsDict |
|||
from fastapi.testclient import TestClient |
|||
|
|||
from ...utils import needs_py39 |
|||
|
|||
|
|||
@pytest.fixture(name="client") |
|||
def get_client(): |
|||
from docs_src.schema_extra_example.tutorial005_an_py39 import app |
|||
|
|||
client = TestClient(app) |
|||
return client |
|||
|
|||
|
|||
@needs_py39 |
|||
def test_post_body_example(client: TestClient): |
|||
response = client.put( |
|||
"/items/5", |
|||
json={ |
|||
"name": "Foo", |
|||
"description": "A very nice Item", |
|||
"price": 35.4, |
|||
"tax": 3.2, |
|||
}, |
|||
) |
|||
assert response.status_code == 200 |
|||
|
|||
|
|||
@needs_py39 |
|||
def test_openapi_schema(client: TestClient) -> None: |
|||
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": { |
|||
"/items/{item_id}": { |
|||
"put": { |
|||
"summary": "Update Item", |
|||
"operationId": "update_item_items__item_id__put", |
|||
"parameters": [ |
|||
{ |
|||
"required": True, |
|||
"schema": {"title": "Item Id", "type": "integer"}, |
|||
"name": "item_id", |
|||
"in": "path", |
|||
} |
|||
], |
|||
"requestBody": { |
|||
"content": { |
|||
"application/json": { |
|||
"schema": IsDict({"$ref": "#/components/schemas/Item"}) |
|||
| IsDict( |
|||
# TODO: remove when deprecating Pydantic v1 |
|||
{ |
|||
"allOf": [ |
|||
{"$ref": "#/components/schemas/Item"} |
|||
], |
|||
"title": "Item", |
|||
} |
|||
), |
|||
"examples": { |
|||
"normal": { |
|||
"summary": "A normal example", |
|||
"description": "A **normal** item works correctly.", |
|||
"value": { |
|||
"name": "Foo", |
|||
"description": "A very nice Item", |
|||
"price": 35.4, |
|||
"tax": 3.2, |
|||
}, |
|||
}, |
|||
"converted": { |
|||
"summary": "An example with converted data", |
|||
"description": "FastAPI can convert price `strings` to actual `numbers` automatically", |
|||
"value": {"name": "Bar", "price": "35.4"}, |
|||
}, |
|||
"invalid": { |
|||
"summary": "Invalid data is rejected with an error", |
|||
"value": { |
|||
"name": "Baz", |
|||
"price": "thirty five point four", |
|||
}, |
|||
}, |
|||
}, |
|||
} |
|||
}, |
|||
"required": True, |
|||
}, |
|||
"responses": { |
|||
"200": { |
|||
"description": "Successful Response", |
|||
"content": {"application/json": {"schema": {}}}, |
|||
}, |
|||
"422": { |
|||
"description": "Validation Error", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"$ref": "#/components/schemas/HTTPValidationError" |
|||
} |
|||
} |
|||
}, |
|||
}, |
|||
}, |
|||
} |
|||
} |
|||
}, |
|||
"components": { |
|||
"schemas": { |
|||
"HTTPValidationError": { |
|||
"title": "HTTPValidationError", |
|||
"type": "object", |
|||
"properties": { |
|||
"detail": { |
|||
"title": "Detail", |
|||
"type": "array", |
|||
"items": {"$ref": "#/components/schemas/ValidationError"}, |
|||
} |
|||
}, |
|||
}, |
|||
"Item": { |
|||
"title": "Item", |
|||
"required": ["name", "price"], |
|||
"type": "object", |
|||
"properties": { |
|||
"name": {"title": "Name", "type": "string"}, |
|||
"description": IsDict( |
|||
{ |
|||
"title": "Description", |
|||
"anyOf": [{"type": "string"}, {"type": "null"}], |
|||
} |
|||
) |
|||
| IsDict( |
|||
# TODO: remove when deprecating Pydantic v1 |
|||
{"title": "Description", "type": "string"} |
|||
), |
|||
"price": {"title": "Price", "type": "number"}, |
|||
"tax": IsDict( |
|||
{ |
|||
"title": "Tax", |
|||
"anyOf": [{"type": "number"}, {"type": "null"}], |
|||
} |
|||
) |
|||
| IsDict( |
|||
# TODO: remove when deprecating Pydantic v1 |
|||
{"title": "Tax", "type": "number"} |
|||
), |
|||
}, |
|||
}, |
|||
"ValidationError": { |
|||
"title": "ValidationError", |
|||
"required": ["loc", "msg", "type"], |
|||
"type": "object", |
|||
"properties": { |
|||
"loc": { |
|||
"title": "Location", |
|||
"type": "array", |
|||
"items": { |
|||
"anyOf": [{"type": "string"}, {"type": "integer"}] |
|||
}, |
|||
}, |
|||
"msg": {"title": "Message", "type": "string"}, |
|||
"type": {"title": "Error Type", "type": "string"}, |
|||
}, |
|||
}, |
|||
} |
|||
}, |
|||
} |
|||
@ -0,0 +1,170 @@ |
|||
import pytest |
|||
from dirty_equals import IsDict |
|||
from fastapi.testclient import TestClient |
|||
|
|||
from ...utils import needs_py310 |
|||
|
|||
|
|||
@pytest.fixture(name="client") |
|||
def get_client(): |
|||
from docs_src.schema_extra_example.tutorial005_py310 import app |
|||
|
|||
client = TestClient(app) |
|||
return client |
|||
|
|||
|
|||
@needs_py310 |
|||
def test_post_body_example(client: TestClient): |
|||
response = client.put( |
|||
"/items/5", |
|||
json={ |
|||
"name": "Foo", |
|||
"description": "A very nice Item", |
|||
"price": 35.4, |
|||
"tax": 3.2, |
|||
}, |
|||
) |
|||
assert response.status_code == 200 |
|||
|
|||
|
|||
@needs_py310 |
|||
def test_openapi_schema(client: TestClient) -> None: |
|||
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": { |
|||
"/items/{item_id}": { |
|||
"put": { |
|||
"summary": "Update Item", |
|||
"operationId": "update_item_items__item_id__put", |
|||
"parameters": [ |
|||
{ |
|||
"required": True, |
|||
"schema": {"title": "Item Id", "type": "integer"}, |
|||
"name": "item_id", |
|||
"in": "path", |
|||
} |
|||
], |
|||
"requestBody": { |
|||
"content": { |
|||
"application/json": { |
|||
"schema": IsDict({"$ref": "#/components/schemas/Item"}) |
|||
| IsDict( |
|||
# TODO: remove when deprecating Pydantic v1 |
|||
{ |
|||
"allOf": [ |
|||
{"$ref": "#/components/schemas/Item"} |
|||
], |
|||
"title": "Item", |
|||
} |
|||
), |
|||
"examples": { |
|||
"normal": { |
|||
"summary": "A normal example", |
|||
"description": "A **normal** item works correctly.", |
|||
"value": { |
|||
"name": "Foo", |
|||
"description": "A very nice Item", |
|||
"price": 35.4, |
|||
"tax": 3.2, |
|||
}, |
|||
}, |
|||
"converted": { |
|||
"summary": "An example with converted data", |
|||
"description": "FastAPI can convert price `strings` to actual `numbers` automatically", |
|||
"value": {"name": "Bar", "price": "35.4"}, |
|||
}, |
|||
"invalid": { |
|||
"summary": "Invalid data is rejected with an error", |
|||
"value": { |
|||
"name": "Baz", |
|||
"price": "thirty five point four", |
|||
}, |
|||
}, |
|||
}, |
|||
} |
|||
}, |
|||
"required": True, |
|||
}, |
|||
"responses": { |
|||
"200": { |
|||
"description": "Successful Response", |
|||
"content": {"application/json": {"schema": {}}}, |
|||
}, |
|||
"422": { |
|||
"description": "Validation Error", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"$ref": "#/components/schemas/HTTPValidationError" |
|||
} |
|||
} |
|||
}, |
|||
}, |
|||
}, |
|||
} |
|||
} |
|||
}, |
|||
"components": { |
|||
"schemas": { |
|||
"HTTPValidationError": { |
|||
"title": "HTTPValidationError", |
|||
"type": "object", |
|||
"properties": { |
|||
"detail": { |
|||
"title": "Detail", |
|||
"type": "array", |
|||
"items": {"$ref": "#/components/schemas/ValidationError"}, |
|||
} |
|||
}, |
|||
}, |
|||
"Item": { |
|||
"title": "Item", |
|||
"required": ["name", "price"], |
|||
"type": "object", |
|||
"properties": { |
|||
"name": {"title": "Name", "type": "string"}, |
|||
"description": IsDict( |
|||
{ |
|||
"title": "Description", |
|||
"anyOf": [{"type": "string"}, {"type": "null"}], |
|||
} |
|||
) |
|||
| IsDict( |
|||
# TODO: remove when deprecating Pydantic v1 |
|||
{"title": "Description", "type": "string"} |
|||
), |
|||
"price": {"title": "Price", "type": "number"}, |
|||
"tax": IsDict( |
|||
{ |
|||
"title": "Tax", |
|||
"anyOf": [{"type": "number"}, {"type": "null"}], |
|||
} |
|||
) |
|||
| IsDict( |
|||
# TODO: remove when deprecating Pydantic v1 |
|||
{"title": "Tax", "type": "number"} |
|||
), |
|||
}, |
|||
}, |
|||
"ValidationError": { |
|||
"title": "ValidationError", |
|||
"required": ["loc", "msg", "type"], |
|||
"type": "object", |
|||
"properties": { |
|||
"loc": { |
|||
"title": "Location", |
|||
"type": "array", |
|||
"items": { |
|||
"anyOf": [{"type": "string"}, {"type": "integer"}] |
|||
}, |
|||
}, |
|||
"msg": {"title": "Message", "type": "string"}, |
|||
"type": {"title": "Error Type", "type": "string"}, |
|||
}, |
|||
}, |
|||
} |
|||
}, |
|||
} |
|||
@ -0,0 +1,147 @@ |
|||
import pytest |
|||
from fastapi.testclient import TestClient |
|||
|
|||
from ...utils import needs_pydanticv2 |
|||
|
|||
|
|||
@pytest.fixture(name="client") |
|||
def get_client() -> TestClient: |
|||
from docs_src.separate_openapi_schemas.tutorial001 import app |
|||
|
|||
client = TestClient(app) |
|||
return client |
|||
|
|||
|
|||
def test_create_item(client: TestClient) -> None: |
|||
response = client.post("/items/", json={"name": "Foo"}) |
|||
assert response.status_code == 200, response.text |
|||
assert response.json() == {"name": "Foo", "description": None} |
|||
|
|||
|
|||
def test_read_items(client: TestClient) -> None: |
|||
response = client.get("/items/") |
|||
assert response.status_code == 200, response.text |
|||
assert response.json() == [ |
|||
{ |
|||
"name": "Portal Gun", |
|||
"description": "Device to travel through the multi-rick-verse", |
|||
}, |
|||
{"name": "Plumbus", "description": None}, |
|||
] |
|||
|
|||
|
|||
@needs_pydanticv2 |
|||
def test_openapi_schema(client: TestClient) -> None: |
|||
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": { |
|||
"/items/": { |
|||
"get": { |
|||
"summary": "Read Items", |
|||
"operationId": "read_items_items__get", |
|||
"responses": { |
|||
"200": { |
|||
"description": "Successful Response", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"items": { |
|||
"$ref": "#/components/schemas/Item-Output" |
|||
}, |
|||
"type": "array", |
|||
"title": "Response Read Items Items Get", |
|||
} |
|||
} |
|||
}, |
|||
} |
|||
}, |
|||
}, |
|||
"post": { |
|||
"summary": "Create Item", |
|||
"operationId": "create_item_items__post", |
|||
"requestBody": { |
|||
"content": { |
|||
"application/json": { |
|||
"schema": {"$ref": "#/components/schemas/Item-Input"} |
|||
} |
|||
}, |
|||
"required": True, |
|||
}, |
|||
"responses": { |
|||
"200": { |
|||
"description": "Successful Response", |
|||
"content": {"application/json": {"schema": {}}}, |
|||
}, |
|||
"422": { |
|||
"description": "Validation Error", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"$ref": "#/components/schemas/HTTPValidationError" |
|||
} |
|||
} |
|||
}, |
|||
}, |
|||
}, |
|||
}, |
|||
} |
|||
}, |
|||
"components": { |
|||
"schemas": { |
|||
"HTTPValidationError": { |
|||
"properties": { |
|||
"detail": { |
|||
"items": {"$ref": "#/components/schemas/ValidationError"}, |
|||
"type": "array", |
|||
"title": "Detail", |
|||
} |
|||
}, |
|||
"type": "object", |
|||
"title": "HTTPValidationError", |
|||
}, |
|||
"Item-Input": { |
|||
"properties": { |
|||
"name": {"type": "string", "title": "Name"}, |
|||
"description": { |
|||
"anyOf": [{"type": "string"}, {"type": "null"}], |
|||
"title": "Description", |
|||
}, |
|||
}, |
|||
"type": "object", |
|||
"required": ["name"], |
|||
"title": "Item", |
|||
}, |
|||
"Item-Output": { |
|||
"properties": { |
|||
"name": {"type": "string", "title": "Name"}, |
|||
"description": { |
|||
"anyOf": [{"type": "string"}, {"type": "null"}], |
|||
"title": "Description", |
|||
}, |
|||
}, |
|||
"type": "object", |
|||
"required": ["name", "description"], |
|||
"title": "Item", |
|||
}, |
|||
"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", |
|||
}, |
|||
} |
|||
}, |
|||
} |
|||
@ -0,0 +1,150 @@ |
|||
import pytest |
|||
from fastapi.testclient import TestClient |
|||
|
|||
from ...utils import needs_py310, needs_pydanticv2 |
|||
|
|||
|
|||
@pytest.fixture(name="client") |
|||
def get_client() -> TestClient: |
|||
from docs_src.separate_openapi_schemas.tutorial001_py310 import app |
|||
|
|||
client = TestClient(app) |
|||
return client |
|||
|
|||
|
|||
@needs_py310 |
|||
def test_create_item(client: TestClient) -> None: |
|||
response = client.post("/items/", json={"name": "Foo"}) |
|||
assert response.status_code == 200, response.text |
|||
assert response.json() == {"name": "Foo", "description": None} |
|||
|
|||
|
|||
@needs_py310 |
|||
def test_read_items(client: TestClient) -> None: |
|||
response = client.get("/items/") |
|||
assert response.status_code == 200, response.text |
|||
assert response.json() == [ |
|||
{ |
|||
"name": "Portal Gun", |
|||
"description": "Device to travel through the multi-rick-verse", |
|||
}, |
|||
{"name": "Plumbus", "description": None}, |
|||
] |
|||
|
|||
|
|||
@needs_py310 |
|||
@needs_pydanticv2 |
|||
def test_openapi_schema(client: TestClient) -> None: |
|||
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": { |
|||
"/items/": { |
|||
"get": { |
|||
"summary": "Read Items", |
|||
"operationId": "read_items_items__get", |
|||
"responses": { |
|||
"200": { |
|||
"description": "Successful Response", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"items": { |
|||
"$ref": "#/components/schemas/Item-Output" |
|||
}, |
|||
"type": "array", |
|||
"title": "Response Read Items Items Get", |
|||
} |
|||
} |
|||
}, |
|||
} |
|||
}, |
|||
}, |
|||
"post": { |
|||
"summary": "Create Item", |
|||
"operationId": "create_item_items__post", |
|||
"requestBody": { |
|||
"content": { |
|||
"application/json": { |
|||
"schema": {"$ref": "#/components/schemas/Item-Input"} |
|||
} |
|||
}, |
|||
"required": True, |
|||
}, |
|||
"responses": { |
|||
"200": { |
|||
"description": "Successful Response", |
|||
"content": {"application/json": {"schema": {}}}, |
|||
}, |
|||
"422": { |
|||
"description": "Validation Error", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"$ref": "#/components/schemas/HTTPValidationError" |
|||
} |
|||
} |
|||
}, |
|||
}, |
|||
}, |
|||
}, |
|||
} |
|||
}, |
|||
"components": { |
|||
"schemas": { |
|||
"HTTPValidationError": { |
|||
"properties": { |
|||
"detail": { |
|||
"items": {"$ref": "#/components/schemas/ValidationError"}, |
|||
"type": "array", |
|||
"title": "Detail", |
|||
} |
|||
}, |
|||
"type": "object", |
|||
"title": "HTTPValidationError", |
|||
}, |
|||
"Item-Input": { |
|||
"properties": { |
|||
"name": {"type": "string", "title": "Name"}, |
|||
"description": { |
|||
"anyOf": [{"type": "string"}, {"type": "null"}], |
|||
"title": "Description", |
|||
}, |
|||
}, |
|||
"type": "object", |
|||
"required": ["name"], |
|||
"title": "Item", |
|||
}, |
|||
"Item-Output": { |
|||
"properties": { |
|||
"name": {"type": "string", "title": "Name"}, |
|||
"description": { |
|||
"anyOf": [{"type": "string"}, {"type": "null"}], |
|||
"title": "Description", |
|||
}, |
|||
}, |
|||
"type": "object", |
|||
"required": ["name", "description"], |
|||
"title": "Item", |
|||
}, |
|||
"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", |
|||
}, |
|||
} |
|||
}, |
|||
} |
|||
@ -0,0 +1,150 @@ |
|||
import pytest |
|||
from fastapi.testclient import TestClient |
|||
|
|||
from ...utils import needs_py39, needs_pydanticv2 |
|||
|
|||
|
|||
@pytest.fixture(name="client") |
|||
def get_client() -> TestClient: |
|||
from docs_src.separate_openapi_schemas.tutorial001_py39 import app |
|||
|
|||
client = TestClient(app) |
|||
return client |
|||
|
|||
|
|||
@needs_py39 |
|||
def test_create_item(client: TestClient) -> None: |
|||
response = client.post("/items/", json={"name": "Foo"}) |
|||
assert response.status_code == 200, response.text |
|||
assert response.json() == {"name": "Foo", "description": None} |
|||
|
|||
|
|||
@needs_py39 |
|||
def test_read_items(client: TestClient) -> None: |
|||
response = client.get("/items/") |
|||
assert response.status_code == 200, response.text |
|||
assert response.json() == [ |
|||
{ |
|||
"name": "Portal Gun", |
|||
"description": "Device to travel through the multi-rick-verse", |
|||
}, |
|||
{"name": "Plumbus", "description": None}, |
|||
] |
|||
|
|||
|
|||
@needs_py39 |
|||
@needs_pydanticv2 |
|||
def test_openapi_schema(client: TestClient) -> None: |
|||
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": { |
|||
"/items/": { |
|||
"get": { |
|||
"summary": "Read Items", |
|||
"operationId": "read_items_items__get", |
|||
"responses": { |
|||
"200": { |
|||
"description": "Successful Response", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"items": { |
|||
"$ref": "#/components/schemas/Item-Output" |
|||
}, |
|||
"type": "array", |
|||
"title": "Response Read Items Items Get", |
|||
} |
|||
} |
|||
}, |
|||
} |
|||
}, |
|||
}, |
|||
"post": { |
|||
"summary": "Create Item", |
|||
"operationId": "create_item_items__post", |
|||
"requestBody": { |
|||
"content": { |
|||
"application/json": { |
|||
"schema": {"$ref": "#/components/schemas/Item-Input"} |
|||
} |
|||
}, |
|||
"required": True, |
|||
}, |
|||
"responses": { |
|||
"200": { |
|||
"description": "Successful Response", |
|||
"content": {"application/json": {"schema": {}}}, |
|||
}, |
|||
"422": { |
|||
"description": "Validation Error", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"$ref": "#/components/schemas/HTTPValidationError" |
|||
} |
|||
} |
|||
}, |
|||
}, |
|||
}, |
|||
}, |
|||
} |
|||
}, |
|||
"components": { |
|||
"schemas": { |
|||
"HTTPValidationError": { |
|||
"properties": { |
|||
"detail": { |
|||
"items": {"$ref": "#/components/schemas/ValidationError"}, |
|||
"type": "array", |
|||
"title": "Detail", |
|||
} |
|||
}, |
|||
"type": "object", |
|||
"title": "HTTPValidationError", |
|||
}, |
|||
"Item-Input": { |
|||
"properties": { |
|||
"name": {"type": "string", "title": "Name"}, |
|||
"description": { |
|||
"anyOf": [{"type": "string"}, {"type": "null"}], |
|||
"title": "Description", |
|||
}, |
|||
}, |
|||
"type": "object", |
|||
"required": ["name"], |
|||
"title": "Item", |
|||
}, |
|||
"Item-Output": { |
|||
"properties": { |
|||
"name": {"type": "string", "title": "Name"}, |
|||
"description": { |
|||
"anyOf": [{"type": "string"}, {"type": "null"}], |
|||
"title": "Description", |
|||
}, |
|||
}, |
|||
"type": "object", |
|||
"required": ["name", "description"], |
|||
"title": "Item", |
|||
}, |
|||
"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", |
|||
}, |
|||
} |
|||
}, |
|||
} |
|||
@ -0,0 +1,133 @@ |
|||
import pytest |
|||
from fastapi.testclient import TestClient |
|||
|
|||
from ...utils import needs_pydanticv2 |
|||
|
|||
|
|||
@pytest.fixture(name="client") |
|||
def get_client() -> TestClient: |
|||
from docs_src.separate_openapi_schemas.tutorial002 import app |
|||
|
|||
client = TestClient(app) |
|||
return client |
|||
|
|||
|
|||
def test_create_item(client: TestClient) -> None: |
|||
response = client.post("/items/", json={"name": "Foo"}) |
|||
assert response.status_code == 200, response.text |
|||
assert response.json() == {"name": "Foo", "description": None} |
|||
|
|||
|
|||
def test_read_items(client: TestClient) -> None: |
|||
response = client.get("/items/") |
|||
assert response.status_code == 200, response.text |
|||
assert response.json() == [ |
|||
{ |
|||
"name": "Portal Gun", |
|||
"description": "Device to travel through the multi-rick-verse", |
|||
}, |
|||
{"name": "Plumbus", "description": None}, |
|||
] |
|||
|
|||
|
|||
@needs_pydanticv2 |
|||
def test_openapi_schema(client: TestClient) -> None: |
|||
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": { |
|||
"/items/": { |
|||
"get": { |
|||
"summary": "Read Items", |
|||
"operationId": "read_items_items__get", |
|||
"responses": { |
|||
"200": { |
|||
"description": "Successful Response", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"items": {"$ref": "#/components/schemas/Item"}, |
|||
"type": "array", |
|||
"title": "Response Read Items Items Get", |
|||
} |
|||
} |
|||
}, |
|||
} |
|||
}, |
|||
}, |
|||
"post": { |
|||
"summary": "Create Item", |
|||
"operationId": "create_item_items__post", |
|||
"requestBody": { |
|||
"content": { |
|||
"application/json": { |
|||
"schema": {"$ref": "#/components/schemas/Item"} |
|||
} |
|||
}, |
|||
"required": True, |
|||
}, |
|||
"responses": { |
|||
"200": { |
|||
"description": "Successful Response", |
|||
"content": {"application/json": {"schema": {}}}, |
|||
}, |
|||
"422": { |
|||
"description": "Validation Error", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"$ref": "#/components/schemas/HTTPValidationError" |
|||
} |
|||
} |
|||
}, |
|||
}, |
|||
}, |
|||
}, |
|||
} |
|||
}, |
|||
"components": { |
|||
"schemas": { |
|||
"HTTPValidationError": { |
|||
"properties": { |
|||
"detail": { |
|||
"items": {"$ref": "#/components/schemas/ValidationError"}, |
|||
"type": "array", |
|||
"title": "Detail", |
|||
} |
|||
}, |
|||
"type": "object", |
|||
"title": "HTTPValidationError", |
|||
}, |
|||
"Item": { |
|||
"properties": { |
|||
"name": {"type": "string", "title": "Name"}, |
|||
"description": { |
|||
"anyOf": [{"type": "string"}, {"type": "null"}], |
|||
"title": "Description", |
|||
}, |
|||
}, |
|||
"type": "object", |
|||
"required": ["name"], |
|||
"title": "Item", |
|||
}, |
|||
"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", |
|||
}, |
|||
} |
|||
}, |
|||
} |
|||
@ -0,0 +1,136 @@ |
|||
import pytest |
|||
from fastapi.testclient import TestClient |
|||
|
|||
from ...utils import needs_py310, needs_pydanticv2 |
|||
|
|||
|
|||
@pytest.fixture(name="client") |
|||
def get_client() -> TestClient: |
|||
from docs_src.separate_openapi_schemas.tutorial002_py310 import app |
|||
|
|||
client = TestClient(app) |
|||
return client |
|||
|
|||
|
|||
@needs_py310 |
|||
def test_create_item(client: TestClient) -> None: |
|||
response = client.post("/items/", json={"name": "Foo"}) |
|||
assert response.status_code == 200, response.text |
|||
assert response.json() == {"name": "Foo", "description": None} |
|||
|
|||
|
|||
@needs_py310 |
|||
def test_read_items(client: TestClient) -> None: |
|||
response = client.get("/items/") |
|||
assert response.status_code == 200, response.text |
|||
assert response.json() == [ |
|||
{ |
|||
"name": "Portal Gun", |
|||
"description": "Device to travel through the multi-rick-verse", |
|||
}, |
|||
{"name": "Plumbus", "description": None}, |
|||
] |
|||
|
|||
|
|||
@needs_py310 |
|||
@needs_pydanticv2 |
|||
def test_openapi_schema(client: TestClient) -> None: |
|||
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": { |
|||
"/items/": { |
|||
"get": { |
|||
"summary": "Read Items", |
|||
"operationId": "read_items_items__get", |
|||
"responses": { |
|||
"200": { |
|||
"description": "Successful Response", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"items": {"$ref": "#/components/schemas/Item"}, |
|||
"type": "array", |
|||
"title": "Response Read Items Items Get", |
|||
} |
|||
} |
|||
}, |
|||
} |
|||
}, |
|||
}, |
|||
"post": { |
|||
"summary": "Create Item", |
|||
"operationId": "create_item_items__post", |
|||
"requestBody": { |
|||
"content": { |
|||
"application/json": { |
|||
"schema": {"$ref": "#/components/schemas/Item"} |
|||
} |
|||
}, |
|||
"required": True, |
|||
}, |
|||
"responses": { |
|||
"200": { |
|||
"description": "Successful Response", |
|||
"content": {"application/json": {"schema": {}}}, |
|||
}, |
|||
"422": { |
|||
"description": "Validation Error", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"$ref": "#/components/schemas/HTTPValidationError" |
|||
} |
|||
} |
|||
}, |
|||
}, |
|||
}, |
|||
}, |
|||
} |
|||
}, |
|||
"components": { |
|||
"schemas": { |
|||
"HTTPValidationError": { |
|||
"properties": { |
|||
"detail": { |
|||
"items": {"$ref": "#/components/schemas/ValidationError"}, |
|||
"type": "array", |
|||
"title": "Detail", |
|||
} |
|||
}, |
|||
"type": "object", |
|||
"title": "HTTPValidationError", |
|||
}, |
|||
"Item": { |
|||
"properties": { |
|||
"name": {"type": "string", "title": "Name"}, |
|||
"description": { |
|||
"anyOf": [{"type": "string"}, {"type": "null"}], |
|||
"title": "Description", |
|||
}, |
|||
}, |
|||
"type": "object", |
|||
"required": ["name"], |
|||
"title": "Item", |
|||
}, |
|||
"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", |
|||
}, |
|||
} |
|||
}, |
|||
} |
|||
@ -0,0 +1,136 @@ |
|||
import pytest |
|||
from fastapi.testclient import TestClient |
|||
|
|||
from ...utils import needs_py39, needs_pydanticv2 |
|||
|
|||
|
|||
@pytest.fixture(name="client") |
|||
def get_client() -> TestClient: |
|||
from docs_src.separate_openapi_schemas.tutorial002_py39 import app |
|||
|
|||
client = TestClient(app) |
|||
return client |
|||
|
|||
|
|||
@needs_py39 |
|||
def test_create_item(client: TestClient) -> None: |
|||
response = client.post("/items/", json={"name": "Foo"}) |
|||
assert response.status_code == 200, response.text |
|||
assert response.json() == {"name": "Foo", "description": None} |
|||
|
|||
|
|||
@needs_py39 |
|||
def test_read_items(client: TestClient) -> None: |
|||
response = client.get("/items/") |
|||
assert response.status_code == 200, response.text |
|||
assert response.json() == [ |
|||
{ |
|||
"name": "Portal Gun", |
|||
"description": "Device to travel through the multi-rick-verse", |
|||
}, |
|||
{"name": "Plumbus", "description": None}, |
|||
] |
|||
|
|||
|
|||
@needs_py39 |
|||
@needs_pydanticv2 |
|||
def test_openapi_schema(client: TestClient) -> None: |
|||
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": { |
|||
"/items/": { |
|||
"get": { |
|||
"summary": "Read Items", |
|||
"operationId": "read_items_items__get", |
|||
"responses": { |
|||
"200": { |
|||
"description": "Successful Response", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"items": {"$ref": "#/components/schemas/Item"}, |
|||
"type": "array", |
|||
"title": "Response Read Items Items Get", |
|||
} |
|||
} |
|||
}, |
|||
} |
|||
}, |
|||
}, |
|||
"post": { |
|||
"summary": "Create Item", |
|||
"operationId": "create_item_items__post", |
|||
"requestBody": { |
|||
"content": { |
|||
"application/json": { |
|||
"schema": {"$ref": "#/components/schemas/Item"} |
|||
} |
|||
}, |
|||
"required": True, |
|||
}, |
|||
"responses": { |
|||
"200": { |
|||
"description": "Successful Response", |
|||
"content": {"application/json": {"schema": {}}}, |
|||
}, |
|||
"422": { |
|||
"description": "Validation Error", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"$ref": "#/components/schemas/HTTPValidationError" |
|||
} |
|||
} |
|||
}, |
|||
}, |
|||
}, |
|||
}, |
|||
} |
|||
}, |
|||
"components": { |
|||
"schemas": { |
|||
"HTTPValidationError": { |
|||
"properties": { |
|||
"detail": { |
|||
"items": {"$ref": "#/components/schemas/ValidationError"}, |
|||
"type": "array", |
|||
"title": "Detail", |
|||
} |
|||
}, |
|||
"type": "object", |
|||
"title": "HTTPValidationError", |
|||
}, |
|||
"Item": { |
|||
"properties": { |
|||
"name": {"type": "string", "title": "Name"}, |
|||
"description": { |
|||
"anyOf": [{"type": "string"}, {"type": "null"}], |
|||
"title": "Description", |
|||
}, |
|||
}, |
|||
"type": "object", |
|||
"required": ["name"], |
|||
"title": "Item", |
|||
}, |
|||
"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", |
|||
}, |
|||
} |
|||
}, |
|||
} |
|||
Loading…
Reference in new issue