mirror of
https://github.com/fastapi/fastapi.git
synced 2026-09-14 13:36:21 +08:00
Sebastián Ramírez
7dad5a820b
* ✨ Update OpenAPI models for JSON Schema 2020-12 and OpenAPI 3.1.0 * ✨ Add support for summary and webhooks * ✨ Update JSON Schema for UploadFiles * ⏪️ Revert making paths optional, to ensure always correctness * ⏪️ Keep UploadFile as format: binary for compatibility with the rest of Pydantic bytes fields in v1 * ✨ Update version of OpenAPI generated to 3.1.0 * ✨ Update the version of Swagger UI * 📝 Update docs about extending OpenAPI * 📝 Update docs and links to refer to OpenAPI 3.1.0 * ✨ Update logic for handling webhooks * ♻️ Update parameter functions and classes, deprecate example and make examples the main field * ✅ Update tests for OpenAPI 3.1.0 * 📝 Update examples for OpenAPI metadata * ✅ Add and update tests for OpenAPI metadata * 📝 Add source example for webhooks * 📝 Update docs for metadata * 📝 Update docs for Schema extra * 📝 Add docs for webhooks * 🔧 Add webhooks docs to MkDocs * ✅ Update tests for extending OpenAPI * ✅ Add tests for webhooks * ♻️ Refactor generation of OpenAPI and JSON Schema with params * 📝 Update source examples for field examples * ✅ Update tests for examples * ➕ Make sure the minimum version of typing-extensions installed has deprecated() (already a dependency of Pydantic) * ✏️ Fix typo in Webhooks example code * 🔥 Remove commented out code of removed nullable field * 🗑️ Add deprecation warnings for example argument * ✅ Update tests to check for deprecation warnings * ✅ Add test for webhooks with security schemes, for coverage * 🍱 Update image for metadata, with new summary * 🍱 Add docs image for Webhooks * 📝 Update docs for webhooks, add docs UI image
448 lines
13 KiB
Python
448 lines
13 KiB
Python
import warnings
|
|
from enum import Enum
|
|
from typing import Any, Callable, List, Optional, Sequence
|
|
|
|
from pydantic.fields import FieldInfo, Undefined
|
|
from typing_extensions import Annotated, deprecated
|
|
|
|
|
|
class ParamTypes(Enum):
|
|
query = "query"
|
|
header = "header"
|
|
path = "path"
|
|
cookie = "cookie"
|
|
|
|
|
|
class Param(FieldInfo):
|
|
in_: ParamTypes
|
|
|
|
def __init__(
|
|
self,
|
|
default: Any = Undefined,
|
|
*,
|
|
alias: Optional[str] = None,
|
|
title: Optional[str] = None,
|
|
description: Optional[str] = None,
|
|
gt: Optional[float] = None,
|
|
ge: Optional[float] = None,
|
|
lt: Optional[float] = None,
|
|
le: Optional[float] = None,
|
|
min_length: Optional[int] = None,
|
|
max_length: Optional[int] = None,
|
|
regex: Optional[str] = None,
|
|
examples: Optional[List[Any]] = None,
|
|
example: Annotated[
|
|
Optional[Any],
|
|
deprecated(
|
|
"Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, "
|
|
"although still supported. Use examples instead."
|
|
),
|
|
] = Undefined,
|
|
deprecated: Optional[bool] = None,
|
|
include_in_schema: bool = True,
|
|
**extra: Any,
|
|
):
|
|
self.deprecated = deprecated
|
|
if example is not Undefined:
|
|
warnings.warn(
|
|
"`example` has been depreacated, please use `examples` instead",
|
|
category=DeprecationWarning,
|
|
stacklevel=1,
|
|
)
|
|
self.example = example
|
|
self.include_in_schema = include_in_schema
|
|
extra_kwargs = {**extra}
|
|
if examples:
|
|
extra_kwargs["examples"] = examples
|
|
super().__init__(
|
|
default=default,
|
|
alias=alias,
|
|
title=title,
|
|
description=description,
|
|
gt=gt,
|
|
ge=ge,
|
|
lt=lt,
|
|
le=le,
|
|
min_length=min_length,
|
|
max_length=max_length,
|
|
regex=regex,
|
|
**extra_kwargs,
|
|
)
|
|
|
|
def __repr__(self) -> str:
|
|
return f"{self.__class__.__name__}({self.default})"
|
|
|
|
|
|
class Path(Param):
|
|
in_ = ParamTypes.path
|
|
|
|
def __init__(
|
|
self,
|
|
default: Any = ...,
|
|
*,
|
|
alias: Optional[str] = None,
|
|
title: Optional[str] = None,
|
|
description: Optional[str] = None,
|
|
gt: Optional[float] = None,
|
|
ge: Optional[float] = None,
|
|
lt: Optional[float] = None,
|
|
le: Optional[float] = None,
|
|
min_length: Optional[int] = None,
|
|
max_length: Optional[int] = None,
|
|
regex: Optional[str] = None,
|
|
examples: Optional[List[Any]] = None,
|
|
example: Annotated[
|
|
Optional[Any],
|
|
deprecated(
|
|
"Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, "
|
|
"although still supported. Use examples instead."
|
|
),
|
|
] = Undefined,
|
|
deprecated: Optional[bool] = None,
|
|
include_in_schema: bool = True,
|
|
**extra: Any,
|
|
):
|
|
assert default is ..., "Path parameters cannot have a default value"
|
|
self.in_ = self.in_
|
|
super().__init__(
|
|
default=default,
|
|
alias=alias,
|
|
title=title,
|
|
description=description,
|
|
gt=gt,
|
|
ge=ge,
|
|
lt=lt,
|
|
le=le,
|
|
min_length=min_length,
|
|
max_length=max_length,
|
|
regex=regex,
|
|
deprecated=deprecated,
|
|
example=example,
|
|
examples=examples,
|
|
include_in_schema=include_in_schema,
|
|
**extra,
|
|
)
|
|
|
|
|
|
class Query(Param):
|
|
in_ = ParamTypes.query
|
|
|
|
def __init__(
|
|
self,
|
|
default: Any = Undefined,
|
|
*,
|
|
alias: Optional[str] = None,
|
|
title: Optional[str] = None,
|
|
description: Optional[str] = None,
|
|
gt: Optional[float] = None,
|
|
ge: Optional[float] = None,
|
|
lt: Optional[float] = None,
|
|
le: Optional[float] = None,
|
|
min_length: Optional[int] = None,
|
|
max_length: Optional[int] = None,
|
|
regex: Optional[str] = None,
|
|
examples: Optional[List[Any]] = None,
|
|
example: Annotated[
|
|
Optional[Any],
|
|
deprecated(
|
|
"Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, "
|
|
"although still supported. Use examples instead."
|
|
),
|
|
] = Undefined,
|
|
deprecated: Optional[bool] = None,
|
|
include_in_schema: bool = True,
|
|
**extra: Any,
|
|
):
|
|
super().__init__(
|
|
default=default,
|
|
alias=alias,
|
|
title=title,
|
|
description=description,
|
|
gt=gt,
|
|
ge=ge,
|
|
lt=lt,
|
|
le=le,
|
|
min_length=min_length,
|
|
max_length=max_length,
|
|
regex=regex,
|
|
deprecated=deprecated,
|
|
example=example,
|
|
examples=examples,
|
|
include_in_schema=include_in_schema,
|
|
**extra,
|
|
)
|
|
|
|
|
|
class Header(Param):
|
|
in_ = ParamTypes.header
|
|
|
|
def __init__(
|
|
self,
|
|
default: Any = Undefined,
|
|
*,
|
|
alias: Optional[str] = None,
|
|
convert_underscores: bool = True,
|
|
title: Optional[str] = None,
|
|
description: Optional[str] = None,
|
|
gt: Optional[float] = None,
|
|
ge: Optional[float] = None,
|
|
lt: Optional[float] = None,
|
|
le: Optional[float] = None,
|
|
min_length: Optional[int] = None,
|
|
max_length: Optional[int] = None,
|
|
regex: Optional[str] = None,
|
|
examples: Optional[List[Any]] = None,
|
|
example: Annotated[
|
|
Optional[Any],
|
|
deprecated(
|
|
"Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, "
|
|
"although still supported. Use examples instead."
|
|
),
|
|
] = Undefined,
|
|
deprecated: Optional[bool] = None,
|
|
include_in_schema: bool = True,
|
|
**extra: Any,
|
|
):
|
|
self.convert_underscores = convert_underscores
|
|
super().__init__(
|
|
default=default,
|
|
alias=alias,
|
|
title=title,
|
|
description=description,
|
|
gt=gt,
|
|
ge=ge,
|
|
lt=lt,
|
|
le=le,
|
|
min_length=min_length,
|
|
max_length=max_length,
|
|
regex=regex,
|
|
deprecated=deprecated,
|
|
example=example,
|
|
examples=examples,
|
|
include_in_schema=include_in_schema,
|
|
**extra,
|
|
)
|
|
|
|
|
|
class Cookie(Param):
|
|
in_ = ParamTypes.cookie
|
|
|
|
def __init__(
|
|
self,
|
|
default: Any = Undefined,
|
|
*,
|
|
alias: Optional[str] = None,
|
|
title: Optional[str] = None,
|
|
description: Optional[str] = None,
|
|
gt: Optional[float] = None,
|
|
ge: Optional[float] = None,
|
|
lt: Optional[float] = None,
|
|
le: Optional[float] = None,
|
|
min_length: Optional[int] = None,
|
|
max_length: Optional[int] = None,
|
|
regex: Optional[str] = None,
|
|
examples: Optional[List[Any]] = None,
|
|
example: Annotated[
|
|
Optional[Any],
|
|
deprecated(
|
|
"Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, "
|
|
"although still supported. Use examples instead."
|
|
),
|
|
] = Undefined,
|
|
deprecated: Optional[bool] = None,
|
|
include_in_schema: bool = True,
|
|
**extra: Any,
|
|
):
|
|
super().__init__(
|
|
default=default,
|
|
alias=alias,
|
|
title=title,
|
|
description=description,
|
|
gt=gt,
|
|
ge=ge,
|
|
lt=lt,
|
|
le=le,
|
|
min_length=min_length,
|
|
max_length=max_length,
|
|
regex=regex,
|
|
deprecated=deprecated,
|
|
example=example,
|
|
examples=examples,
|
|
include_in_schema=include_in_schema,
|
|
**extra,
|
|
)
|
|
|
|
|
|
class Body(FieldInfo):
|
|
def __init__(
|
|
self,
|
|
default: Any = Undefined,
|
|
*,
|
|
embed: bool = False,
|
|
media_type: str = "application/json",
|
|
alias: Optional[str] = None,
|
|
title: Optional[str] = None,
|
|
description: Optional[str] = None,
|
|
gt: Optional[float] = None,
|
|
ge: Optional[float] = None,
|
|
lt: Optional[float] = None,
|
|
le: Optional[float] = None,
|
|
min_length: Optional[int] = None,
|
|
max_length: Optional[int] = None,
|
|
regex: Optional[str] = None,
|
|
examples: Optional[List[Any]] = None,
|
|
example: Annotated[
|
|
Optional[Any],
|
|
deprecated(
|
|
"Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, "
|
|
"although still supported. Use examples instead."
|
|
),
|
|
] = Undefined,
|
|
**extra: Any,
|
|
):
|
|
self.embed = embed
|
|
self.media_type = media_type
|
|
if example is not Undefined:
|
|
warnings.warn(
|
|
"`example` has been depreacated, please use `examples` instead",
|
|
category=DeprecationWarning,
|
|
stacklevel=1,
|
|
)
|
|
self.example = example
|
|
extra_kwargs = {**extra}
|
|
if examples is not None:
|
|
extra_kwargs["examples"] = examples
|
|
super().__init__(
|
|
default=default,
|
|
alias=alias,
|
|
title=title,
|
|
description=description,
|
|
gt=gt,
|
|
ge=ge,
|
|
lt=lt,
|
|
le=le,
|
|
min_length=min_length,
|
|
max_length=max_length,
|
|
regex=regex,
|
|
**extra_kwargs,
|
|
)
|
|
|
|
def __repr__(self) -> str:
|
|
return f"{self.__class__.__name__}({self.default})"
|
|
|
|
|
|
class Form(Body):
|
|
def __init__(
|
|
self,
|
|
default: Any = Undefined,
|
|
*,
|
|
media_type: str = "application/x-www-form-urlencoded",
|
|
alias: Optional[str] = None,
|
|
title: Optional[str] = None,
|
|
description: Optional[str] = None,
|
|
gt: Optional[float] = None,
|
|
ge: Optional[float] = None,
|
|
lt: Optional[float] = None,
|
|
le: Optional[float] = None,
|
|
min_length: Optional[int] = None,
|
|
max_length: Optional[int] = None,
|
|
regex: Optional[str] = None,
|
|
examples: Optional[List[Any]] = None,
|
|
example: Annotated[
|
|
Optional[Any],
|
|
deprecated(
|
|
"Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, "
|
|
"although still supported. Use examples instead."
|
|
),
|
|
] = Undefined,
|
|
**extra: Any,
|
|
):
|
|
super().__init__(
|
|
default=default,
|
|
embed=True,
|
|
media_type=media_type,
|
|
alias=alias,
|
|
title=title,
|
|
description=description,
|
|
gt=gt,
|
|
ge=ge,
|
|
lt=lt,
|
|
le=le,
|
|
min_length=min_length,
|
|
max_length=max_length,
|
|
regex=regex,
|
|
example=example,
|
|
examples=examples,
|
|
**extra,
|
|
)
|
|
|
|
|
|
class File(Form):
|
|
def __init__(
|
|
self,
|
|
default: Any = Undefined,
|
|
*,
|
|
media_type: str = "multipart/form-data",
|
|
alias: Optional[str] = None,
|
|
title: Optional[str] = None,
|
|
description: Optional[str] = None,
|
|
gt: Optional[float] = None,
|
|
ge: Optional[float] = None,
|
|
lt: Optional[float] = None,
|
|
le: Optional[float] = None,
|
|
min_length: Optional[int] = None,
|
|
max_length: Optional[int] = None,
|
|
regex: Optional[str] = None,
|
|
examples: Optional[List[Any]] = None,
|
|
example: Annotated[
|
|
Optional[Any],
|
|
deprecated(
|
|
"Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, "
|
|
"although still supported. Use examples instead."
|
|
),
|
|
] = Undefined,
|
|
**extra: Any,
|
|
):
|
|
super().__init__(
|
|
default=default,
|
|
media_type=media_type,
|
|
alias=alias,
|
|
title=title,
|
|
description=description,
|
|
gt=gt,
|
|
ge=ge,
|
|
lt=lt,
|
|
le=le,
|
|
min_length=min_length,
|
|
max_length=max_length,
|
|
regex=regex,
|
|
example=example,
|
|
examples=examples,
|
|
**extra,
|
|
)
|
|
|
|
|
|
class Depends:
|
|
def __init__(
|
|
self, dependency: Optional[Callable[..., Any]] = None, *, use_cache: bool = True
|
|
):
|
|
self.dependency = dependency
|
|
self.use_cache = use_cache
|
|
|
|
def __repr__(self) -> str:
|
|
attr = getattr(self.dependency, "__name__", type(self.dependency).__name__)
|
|
cache = "" if self.use_cache else ", use_cache=False"
|
|
return f"{self.__class__.__name__}({attr}{cache})"
|
|
|
|
|
|
class Security(Depends):
|
|
def __init__(
|
|
self,
|
|
dependency: Optional[Callable[..., Any]] = None,
|
|
*,
|
|
scopes: Optional[Sequence[str]] = None,
|
|
use_cache: bool = True,
|
|
):
|
|
super().__init__(dependency=dependency, use_cache=use_cache)
|
|
self.scopes = scopes or []
|