mirror/fastapi
1
0
Fork 0
mirror of https://github.com/fastapi/fastapi.git synced 2026-04-27 10:18:11 -04:00
Code Issues Packages Projects Releases Wiki Activity

✨ Add support for disabling the separation of input and output JSON Schemas in OpenAPI with Pydantic v2 (#10145)

Browse Source 
* 📝 Add docs for Separate OpenAPI Schemas for Input and Output

* 🔧 Add new docs page to MkDocs config

* ✨ Add separate_input_output_schemas parameter to FastAPI class

* 📝 Add source examples for separating OpenAPI schemas

* ✅ Add tests for separated OpenAPI schemas

* 📝 Add source examples for Python 3.10, 3.9, and 3.7+

* 📝 Update docs for Separate OpenAPI Schemas with new multi-version examples

* ✅ Add and update tests for different Python versions

* ✅ Add tests for corner cases with separate_input_output_schemas

* 📝 Update tutorial to use Union instead of Optional

* 🐛 Fix type annotations

* 🐛 Fix correct import in test

* 💄 Add CSS to simulate browser windows for screenshots

* ➕ Add playwright as a dev dependency to automate generating screenshots

* 🔨 Add Playwright scripts to generate screenshots for new docs

* 📝 Update docs, tweak text to match screenshots

* 🍱 Add screenshots for new docs
This commit is contained in:
Sebastián Ramírez
2023-08-25 21:10:22 +02:00
committed by GitHub
parent 10a127ea4a
commit ea43f227e5
31 changed files with 1950 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

0
tests/test_tutorial/test_separate_openapi_schemas/__init__.py Normal file
View File

147
tests/test_tutorial/test_separate_openapi_schemas/test_tutorial001.py Normal file
View File

@@ -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",
},
}
},
}

150
tests/test_tutorial/test_separate_openapi_schemas/test_tutorial001_py310.py Normal file
View File

@@ -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",
},
}
},
}

150
tests/test_tutorial/test_separate_openapi_schemas/test_tutorial001_py39.py Normal file
View File

@@ -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",
},
}
},
}

133
tests/test_tutorial/test_separate_openapi_schemas/test_tutorial002.py Normal file
View File

@@ -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",
},
}
},
}

136
tests/test_tutorial/test_separate_openapi_schemas/test_tutorial002_py310.py Normal file
View File

@@ -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",
},
}
},
}

136
tests/test_tutorial/test_separate_openapi_schemas/test_tutorial002_py39.py Normal file
View File

@@ -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",
},
}
},
}