Add support for shared/top-level parameters (dependencies, tags, etc) (#2434)

*  Add Default and DefaultPlaceholder data structures

to handle defaults and overrides

*  Add utils to get values by priority handling DefaultPlaceholders

*  Add support for top-level parameters in FastAPI, APIRouter, include_router

including: prefix, tags, dependencies, deprecated, include_in_schema, responses, default_response_class, callbacks

* ♻️ Update openapi utils to handle DefaultPlaceholder for response_class

* 📝 Update bigger-application example code to use top-level params

and showcase them in APIRouter, FastAPI, include_router

* 📝 Update docs for Bigger Applications, include diagrams, top-level params

* 🔥 Simplify code and docs for callbacks as default_response_class is no longer required

* 📝 Add docs for top-level dependencies, in FastAPI()

* 📝 Add docs reference to top-level dependencies in docs for decorator

*  Update/increase tests for Bigger Applications including shared parameters

*  Add tests for top-level dependencies in FastAPI()

*  Add tests for internal DefaultPlaceholder

*  Update/increase tests for callbacks with top-level parameters

*  Add LOTS of tests covering branches and cases for shared parameters

in top-level FastAPI, path operations, include_router, APIRouter, its path operations, nested include_router, nested APIRouter, and its path operations

* 🎨 Format/reorder parameters for consistency in FastAPI, APIRouter, include_router
This commit is contained in:
Sebastián Ramírez
2020-11-29 18:32:18 +01:00
committed by GitHub
parent d550738fa2
commit 313bbe802f
26 changed files with 7807 additions and 308 deletions

View File

@@ -11,32 +11,17 @@ openapi_schema = {
"paths": {
"/users/": {
"get": {
"responses": {
"200": {
"description": "Successful Response",
"content": {"application/json": {"schema": {}}},
}
},
"tags": ["users"],
"summary": "Read Users",
"operationId": "read_users_users__get",
}
},
"/users/me": {
"get": {
"responses": {
"200": {
"description": "Successful Response",
"content": {"application/json": {"schema": {}}},
"parameters": [
{
"required": True,
"schema": {"title": "Token", "type": "string"},
"name": "token",
"in": "query",
}
},
"tags": ["users"],
"summary": "Read User Me",
"operationId": "read_user_me_users_me_get",
}
},
"/users/{username}": {
"get": {
],
"responses": {
"200": {
"description": "Successful Response",
@@ -53,6 +38,41 @@ openapi_schema = {
},
},
},
}
},
"/users/me": {
"get": {
"tags": ["users"],
"summary": "Read User Me",
"operationId": "read_user_me_users_me_get",
"parameters": [
{
"required": True,
"schema": {"title": "Token", "type": "string"},
"name": "token",
"in": "query",
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {"application/json": {"schema": {}}},
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
},
},
}
},
"/users/{username}": {
"get": {
"tags": ["users"],
"summary": "Read User",
"operationId": "read_user_users__username__get",
@@ -62,14 +82,15 @@ openapi_schema = {
"schema": {"title": "Username", "type": "string"},
"name": "username",
"in": "path",
}
},
{
"required": True,
"schema": {"title": "Token", "type": "string"},
"name": "token",
"in": "query",
},
],
}
},
"/items/": {
"get": {
"responses": {
"404": {"description": "Not found"},
"200": {
"description": "Successful Response",
"content": {"application/json": {"schema": {}}},
@@ -85,27 +106,33 @@ openapi_schema = {
},
},
},
}
},
"/items/": {
"get": {
"tags": ["items"],
"summary": "Read Items",
"operationId": "read_items_items__get",
"parameters": [
{
"required": True,
"schema": {"title": "Token", "type": "string"},
"name": "token",
"in": "query",
},
{
"required": True,
"schema": {"title": "X-Token", "type": "string"},
"name": "x-token",
"in": "header",
}
},
],
}
},
"/items/{item_id}": {
"get": {
"responses": {
"404": {"description": "Not found"},
"200": {
"description": "Successful Response",
"content": {"application/json": {"schema": {}}},
},
"404": {"description": "Not found"},
"422": {
"description": "Validation Error",
"content": {
@@ -117,6 +144,10 @@ openapi_schema = {
},
},
},
}
},
"/items/{item_id}": {
"get": {
"tags": ["items"],
"summary": "Read Item",
"operationId": "read_item_items__item_id__get",
@@ -127,6 +158,12 @@ openapi_schema = {
"name": "item_id",
"in": "path",
},
{
"required": True,
"schema": {"title": "Token", "type": "string"},
"name": "token",
"in": "query",
},
{
"required": True,
"schema": {"title": "X-Token", "type": "string"},
@@ -134,11 +171,119 @@ openapi_schema = {
"in": "header",
},
],
"responses": {
"200": {
"description": "Successful Response",
"content": {"application/json": {"schema": {}}},
},
"404": {"description": "Not found"},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
},
},
},
"put": {
"tags": ["items", "custom"],
"summary": "Update Item",
"operationId": "update_item_items__item_id__put",
"parameters": [
{
"required": True,
"schema": {"title": "Item Id", "type": "string"},
"name": "item_id",
"in": "path",
},
{
"required": True,
"schema": {"title": "Token", "type": "string"},
"name": "token",
"in": "query",
},
{
"required": True,
"schema": {"title": "X-Token", "type": "string"},
"name": "x-token",
"in": "header",
},
],
"responses": {
"200": {
"description": "Successful Response",
"content": {"application/json": {"schema": {}}},
},
"404": {"description": "Not found"},
"403": {"description": "Operation forbidden"},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
},
},
},
},
"/admin/": {
"post": {
"tags": ["admin"],
"summary": "Update Admin",
"operationId": "update_admin_admin__post",
"parameters": [
{
"required": True,
"schema": {"title": "Token", "type": "string"},
"name": "token",
"in": "query",
},
{
"required": True,
"schema": {"title": "X-Token", "type": "string"},
"name": "x-token",
"in": "header",
},
],
"responses": {
"200": {
"description": "Successful Response",
"content": {"application/json": {"schema": {}}},
},
"418": {"description": "I'm a teapot"},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
},
},
}
},
"/": {
"get": {
"summary": "Root",
"operationId": "root__get",
"parameters": [
{
"required": True,
"schema": {"title": "Token", "type": "string"},
"name": "token",
"in": "query",
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {"application/json": {"schema": {}}},
@@ -154,28 +299,22 @@ openapi_schema = {
},
},
},
"tags": ["custom", "items"],
"summary": "Update Item",
"operationId": "update_item_items__item_id__put",
"parameters": [
{
"required": True,
"schema": {"title": "Item Id", "type": "string"},
"name": "item_id",
"in": "path",
},
{
"required": True,
"schema": {"title": "X-Token", "type": "string"},
"name": "x-token",
"in": "header",
},
],
},
}
},
},
"components": {
"schemas": {
"HTTPValidationError": {
"title": "HTTPValidationError",
"type": "object",
"properties": {
"detail": {
"title": "Detail",
"type": "array",
"items": {"$ref": "#/components/schemas/ValidationError"},
}
},
},
"ValidationError": {
"title": "ValidationError",
"required": ["loc", "msg", "type"],
@@ -190,49 +329,64 @@ openapi_schema = {
"type": {"title": "Error Type", "type": "string"},
},
},
"HTTPValidationError": {
"title": "HTTPValidationError",
"type": "object",
"properties": {
"detail": {
"title": "Detail",
"type": "array",
"items": {"$ref": "#/components/schemas/ValidationError"},
}
},
},
}
},
}
no_jessica = {
"detail": [
{
"loc": ["query", "token"],
"msg": "field required",
"type": "value_error.missing",
},
]
}
@pytest.mark.parametrize(
"path,expected_status,expected_response,headers",
[
("/users", 200, [{"username": "Foo"}, {"username": "Bar"}], {}),
("/users/foo", 200, {"username": "foo"}, {}),
("/users/me", 200, {"username": "fakecurrentuser"}, {}),
(
"/items",
"/users?token=jessica",
200,
[{"name": "Item Foo"}, {"name": "item Bar"}],
[{"username": "Rick"}, {"username": "Morty"}],
{},
),
("/users", 422, no_jessica, {}),
("/users/foo?token=jessica", 200, {"username": "foo"}, {}),
("/users/foo", 422, no_jessica, {}),
("/users/me?token=jessica", 200, {"username": "fakecurrentuser"}, {}),
("/users/me", 422, no_jessica, {}),
(
"/items?token=jessica",
200,
{"plumbus": {"name": "Plumbus"}, "gun": {"name": "Portal Gun"}},
{"X-Token": "fake-super-secret-token"},
),
("/items", 422, no_jessica, {"X-Token": "fake-super-secret-token"}),
(
"/items/bar",
"/items/plumbus?token=jessica",
200,
{"name": "Fake Specific Item", "item_id": "bar"},
{"name": "Plumbus", "item_id": "plumbus"},
{"X-Token": "fake-super-secret-token"},
),
("/items", 400, {"detail": "X-Token header invalid"}, {"X-Token": "invalid"}),
("/items/plumbus", 422, no_jessica, {"X-Token": "fake-super-secret-token"}),
(
"/items/bar",
"/items?token=jessica",
400,
{"detail": "X-Token header invalid"},
{"X-Token": "invalid"},
),
(
"/items",
"/items/bar?token=jessica",
400,
{"detail": "X-Token header invalid"},
{"X-Token": "invalid"},
),
(
"/items?token=jessica",
422,
{
"detail": [
@@ -246,7 +400,7 @@ openapi_schema = {
{},
),
(
"/items/bar",
"/items/plumbus?token=jessica",
422,
{
"detail": [
@@ -259,6 +413,8 @@ openapi_schema = {
},
{},
),
("/?token=jessica", 200, {"message": "Hello Bigger Applications!"}, {}),
("/", 422, no_jessica, {}),
("/openapi.json", 200, openapi_schema, {}),
],
)
@@ -273,11 +429,16 @@ def test_put_no_header():
assert response.status_code == 422, response.text
assert response.json() == {
"detail": [
{
"loc": ["query", "token"],
"msg": "field required",
"type": "value_error.missing",
},
{
"loc": ["header", "x-token"],
"msg": "field required",
"type": "value_error.missing",
}
},
]
}
@@ -289,12 +450,30 @@ def test_put_invalid_header():
def test_put():
response = client.put("/items/foo", headers={"X-Token": "fake-super-secret-token"})
response = client.put(
"/items/plumbus?token=jessica", headers={"X-Token": "fake-super-secret-token"}
)
assert response.status_code == 200, response.text
assert response.json() == {"item_id": "foo", "name": "The Fighters"}
assert response.json() == {"item_id": "plumbus", "name": "The great Plumbus"}
def test_put_forbidden():
response = client.put("/items/bar", headers={"X-Token": "fake-super-secret-token"})
response = client.put(
"/items/bar?token=jessica", headers={"X-Token": "fake-super-secret-token"}
)
assert response.status_code == 403, response.text
assert response.json() == {"detail": "You can only update the item: foo"}
assert response.json() == {"detail": "You can only update the item: plumbus"}
def test_admin():
response = client.post(
"/admin/?token=jessica", headers={"X-Token": "fake-super-secret-token"}
)
assert response.status_code == 200, response.text
assert response.json() == {"message": "Admin getting schwifty"}
def test_admin_invalid_header():
response = client.post("/admin/", headers={"X-Token": "invalid"})
assert response.status_code == 400, response.text
assert response.json() == {"detail": "X-Token header invalid"}

View File

@@ -0,0 +1,209 @@
from fastapi.testclient import TestClient
from docs_src.dependencies.tutorial012 import app
client = TestClient(app)
openapi_schema = {
"openapi": "3.0.2",
"info": {"title": "FastAPI", "version": "0.1.0"},
"paths": {
"/items/": {
"get": {
"summary": "Read Items",
"operationId": "read_items_items__get",
"parameters": [
{
"required": True,
"schema": {"title": "X-Token", "type": "string"},
"name": "x-token",
"in": "header",
},
{
"required": True,
"schema": {"title": "X-Key", "type": "string"},
"name": "x-key",
"in": "header",
},
],
"responses": {
"200": {
"description": "Successful Response",
"content": {"application/json": {"schema": {}}},
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
},
},
}
},
"/users/": {
"get": {
"summary": "Read Users",
"operationId": "read_users_users__get",
"parameters": [
{
"required": True,
"schema": {"title": "X-Token", "type": "string"},
"name": "x-token",
"in": "header",
},
{
"required": True,
"schema": {"title": "X-Key", "type": "string"},
"name": "x-key",
"in": "header",
},
],
"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"},
}
},
},
"ValidationError": {
"title": "ValidationError",
"required": ["loc", "msg", "type"],
"type": "object",
"properties": {
"loc": {
"title": "Location",
"type": "array",
"items": {"type": "string"},
},
"msg": {"title": "Message", "type": "string"},
"type": {"title": "Error Type", "type": "string"},
},
},
}
},
}
def test_openapi_schema():
response = client.get("/openapi.json")
assert response.status_code == 200, response.text
assert response.json() == openapi_schema
def test_get_no_headers_items():
response = client.get("/items/")
assert response.status_code == 422, response.text
assert response.json() == {
"detail": [
{
"loc": ["header", "x-token"],
"msg": "field required",
"type": "value_error.missing",
},
{
"loc": ["header", "x-key"],
"msg": "field required",
"type": "value_error.missing",
},
]
}
def test_get_no_headers_users():
response = client.get("/users/")
assert response.status_code == 422, response.text
assert response.json() == {
"detail": [
{
"loc": ["header", "x-token"],
"msg": "field required",
"type": "value_error.missing",
},
{
"loc": ["header", "x-key"],
"msg": "field required",
"type": "value_error.missing",
},
]
}
def test_get_invalid_one_header_items():
response = client.get("/items/", headers={"X-Token": "invalid"})
assert response.status_code == 400, response.text
assert response.json() == {"detail": "X-Token header invalid"}
def test_get_invalid_one_users():
response = client.get("/users/", headers={"X-Token": "invalid"})
assert response.status_code == 400, response.text
assert response.json() == {"detail": "X-Token header invalid"}
def test_get_invalid_second_header_items():
response = client.get(
"/items/", headers={"X-Token": "fake-super-secret-token", "X-Key": "invalid"}
)
assert response.status_code == 400, response.text
assert response.json() == {"detail": "X-Key header invalid"}
def test_get_invalid_second_header_users():
response = client.get(
"/users/", headers={"X-Token": "fake-super-secret-token", "X-Key": "invalid"}
)
assert response.status_code == 400, response.text
assert response.json() == {"detail": "X-Key header invalid"}
def test_get_valid_headers_items():
response = client.get(
"/items/",
headers={
"X-Token": "fake-super-secret-token",
"X-Key": "fake-super-secret-key",
},
)
assert response.status_code == 200, response.text
assert response.json() == [{"item": "Portal Gun"}, {"item": "Plumbus"}]
def test_get_valid_headers_users():
response = client.get(
"/users/",
headers={
"X-Token": "fake-super-secret-token",
"X-Key": "fake-super-secret-key",
},
)
assert response.status_code == 200, response.text
assert response.json() == [{"username": "Rick"}, {"username": "Morty"}]