mirror
/
tiangolo.fastapi
mirror of https://github.com/tiangolo/fastapi
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

Use griffe to parse docstrings and add descriptions

pull/13767/head
Konstantin Zangerle 1 month ago
parent
b2d742074c
commit
0e5dca336e
3 changed files with 52 additions and 23 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 27
      fastapi/openapi/utils.py
  2. 47
      fastapi/routing.py
  3. 1
      pyproject.toml

27
fastapi/openapi/utils.py
View File

@ -100,6 +100,7 @@ def _get_openapi_operation_parameters(
field_mapping: Dict[ field_mapping: Dict[
Tuple[ModelField, Literal["validation", "serialization"]], JsonSchemaValue Tuple[ModelField, Literal["validation", "serialization"]], JsonSchemaValue
], ],
field_docstring: Dict[str, str] | None = None,
separate_input_output_schemas: bool = True, separate_input_output_schemas: bool = True,
) -> List[Dict[str, Any]]: ) -> List[Dict[str, Any]]:
parameters = [] parameters = []
@ -115,6 +116,7 @@ def _get_openapi_operation_parameters(
(ParamTypes.cookie, cookie_params), (ParamTypes.cookie, cookie_params),
] ]
default_convert_underscores = True default_convert_underscores = True
field_docstring = field_docstring or {}
if len(flat_dependant.header_params) == 1: if len(flat_dependant.header_params) == 1:
first_field = flat_dependant.header_params[0] first_field = flat_dependant.header_params[0]
if lenient_issubclass(first_field.type_, BaseModel): if lenient_issubclass(first_field.type_, BaseModel):
@ -155,6 +157,8 @@ def _get_openapi_operation_parameters(
} }
if field_info.description: if field_info.description:
parameter["description"] = field_info.description parameter["description"] = field_info.description
elif param.name in field_docstring:
parameter["description"] = field_docstring[param.name]
openapi_examples = getattr(field_info, "openapi_examples", None) openapi_examples = getattr(field_info, "openapi_examples", None)
example = getattr(field_info, "example", None) example = getattr(field_info, "example", None)
if openapi_examples: if openapi_examples:
@ -232,8 +236,14 @@ def get_openapi_operation_metadata(
if route.tags: if route.tags:
operation["tags"] = route.tags operation["tags"] = route.tags
operation["summary"] = generate_operation_summary(route=route, method=method) operation["summary"] = generate_operation_summary(route=route, method=method)
if route.parsed_docstring:
operation["description"] = "\n\n".join(
[i.value for i in route.parsed_docstring if i.kind == "text"]
)
if route.description: if route.description:
operation["description"] = route.description operation["description"] = route.description
operation["description"] = operation["description"].split("\f")[0].strip()
operation_id = route.operation_id or route.unique_id operation_id = route.operation_id or route.unique_id
if operation_id in operation_ids: if operation_id in operation_ids:
message = ( message = (
@ -273,6 +283,10 @@ def get_openapi_path(
assert current_response_class, "A response class is needed to generate OpenAPI" assert current_response_class, "A response class is needed to generate OpenAPI"
route_response_media_type: Optional[str] = current_response_class.media_type route_response_media_type: Optional[str] = current_response_class.media_type
if route.include_in_schema: if route.include_in_schema:
args = [i.value for i in route.parsed_docstring if i.kind == "parameters"]
args_docstring_mapping = (
{a.name: a.description for a in args[0]} if len(args) == 1 else {}
)
for method in route.methods: for method in route.methods:
operation = get_openapi_operation_metadata( operation = get_openapi_operation_metadata(
route=route, method=method, operation_ids=operation_ids route=route, method=method, operation_ids=operation_ids
@ -292,6 +306,7 @@ def get_openapi_path(
model_name_map=model_name_map, model_name_map=model_name_map,
field_mapping=field_mapping, field_mapping=field_mapping,
separate_input_output_schemas=separate_input_output_schemas, separate_input_output_schemas=separate_input_output_schemas,
field_docstring=args_docstring_mapping,
) )
parameters.extend(operation_parameters) parameters.extend(operation_parameters)
if parameters: if parameters:
@ -348,9 +363,19 @@ def get_openapi_path(
if status_code_param is not None: if status_code_param is not None:
if isinstance(status_code_param.default, int): if isinstance(status_code_param.default, int):
status_code = str(status_code_param.default) status_code = str(status_code_param.default)
response_description = ""
if route.parsed_docstring:
ret = [i.value for i in route.parsed_docstring if i.kind == "returns"]
response_description = (
",".join(x.description for x in ret[0])
if len(ret) == 1
else "Successful Response"
)
if route.response_description:
response_description = route.response_description
operation.setdefault("responses", {}).setdefault(status_code, {})[ operation.setdefault("responses", {}).setdefault(status_code, {})[
"description" "description"
] = route.response_description ] = response_description
if route_response_media_type and is_body_allowed_for_status_code( if route_response_media_type and is_body_allowed_for_status_code(
route.status_code route.status_code
): ):

47
fastapi/routing.py
View File

@ -1,7 +1,6 @@
import asyncio import asyncio
import dataclasses import dataclasses
import email.message import email.message
import inspect
import json import json
from contextlib import AsyncExitStack, asynccontextmanager from contextlib import AsyncExitStack, asynccontextmanager
from enum import Enum, IntEnum from enum import Enum, IntEnum
@ -56,6 +55,7 @@ from fastapi.utils import (
get_value_or_default, get_value_or_default,
is_body_allowed_for_status_code, is_body_allowed_for_status_code,
) )
from griffe import Docstring
from pydantic import BaseModel from pydantic import BaseModel
from starlette import routing from starlette import routing
from starlette.concurrency import run_in_threadpool from starlette.concurrency import run_in_threadpool
@ -437,7 +437,7 @@ class APIRoute(routing.Route):
dependencies: Optional[Sequence[params.Depends]] = None, dependencies: Optional[Sequence[params.Depends]] = None,
summary: Optional[str] = None, summary: Optional[str] = None,
description: Optional[str] = None, description: Optional[str] = None,
response_description: str = "Successful Response", response_description: Optional[str] = None,
responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None, responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None,
deprecated: Optional[bool] = None, deprecated: Optional[bool] = None,
name: Optional[str] = None, name: Optional[str] = None,
@ -528,10 +528,13 @@ class APIRoute(routing.Route):
self.response_field = None # type: ignore self.response_field = None # type: ignore
self.secure_cloned_response_field = None self.secure_cloned_response_field = None
self.dependencies = list(dependencies or []) self.dependencies = list(dependencies or [])
self.description = description or inspect.cleandoc(self.endpoint.__doc__ or "") self.description = description
self.docstring = self.endpoint.__doc__ or ""
self.parsed_docstring = Docstring(
self.docstring, parser="google", parser_options={"warnings": False}
).parsed
# if a "form feed" character (page break) is found in the description text, # if a "form feed" character (page break) is found in the description text,
# truncate description text to the content preceding the first "form feed" # truncate description text to the content preceding the first "form feed"
self.description = self.description.split("\f")[0].strip()
response_fields = {} response_fields = {}
for additional_status_code, response in self.responses.items(): for additional_status_code, response in self.responses.items():
assert isinstance(response, dict), "An additional response must be a dict" assert isinstance(response, dict), "An additional response must be a dict"
@ -889,7 +892,7 @@ class APIRouter(routing.Router):
dependencies: Optional[Sequence[params.Depends]] = None, dependencies: Optional[Sequence[params.Depends]] = None,
summary: Optional[str] = None, summary: Optional[str] = None,
description: Optional[str] = None, description: Optional[str] = None,
response_description: str = "Successful Response", response_description: Optional[str] = None,
responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None, responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None,
deprecated: Optional[bool] = None, deprecated: Optional[bool] = None,
methods: Optional[Union[Set[str], List[str]]] = None, methods: Optional[Union[Set[str], List[str]]] = None,
@ -970,7 +973,7 @@ class APIRouter(routing.Router):
dependencies: Optional[Sequence[params.Depends]] = None, dependencies: Optional[Sequence[params.Depends]] = None,
summary: Optional[str] = None, summary: Optional[str] = None,
description: Optional[str] = None, description: Optional[str] = None,
response_description: str = "Successful Response", response_description: Optional[str] = None,
responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None, responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None,
deprecated: Optional[bool] = None, deprecated: Optional[bool] = None,
methods: Optional[List[str]] = None, methods: Optional[List[str]] = None,
@ -1480,7 +1483,7 @@ class APIRouter(routing.Router):
), ),
] = None, ] = None,
response_description: Annotated[ response_description: Annotated[
str, Optional[str],
Doc( Doc(
""" """
The description for the default response. The description for the default response.
@ -1488,7 +1491,7 @@ class APIRouter(routing.Router):
It will be added to the generated OpenAPI (e.g. visible at `/docs`). It will be added to the generated OpenAPI (e.g. visible at `/docs`).
""" """
), ),
] = "Successful Response", ] = None,
responses: Annotated[ responses: Annotated[
Optional[Dict[Union[int, str], Dict[str, Any]]], Optional[Dict[Union[int, str], Dict[str, Any]]],
Doc( Doc(
@ -1857,7 +1860,7 @@ class APIRouter(routing.Router):
), ),
] = None, ] = None,
response_description: Annotated[ response_description: Annotated[
str, Optional[str],
Doc( Doc(
""" """
The description for the default response. The description for the default response.
@ -1865,7 +1868,7 @@ class APIRouter(routing.Router):
It will be added to the generated OpenAPI (e.g. visible at `/docs`). It will be added to the generated OpenAPI (e.g. visible at `/docs`).
""" """
), ),
] = "Successful Response", ] = None,
responses: Annotated[ responses: Annotated[
Optional[Dict[Union[int, str], Dict[str, Any]]], Optional[Dict[Union[int, str], Dict[str, Any]]],
Doc( Doc(
@ -2239,7 +2242,7 @@ class APIRouter(routing.Router):
), ),
] = None, ] = None,
response_description: Annotated[ response_description: Annotated[
str, Optional[str],
Doc( Doc(
""" """
The description for the default response. The description for the default response.
@ -2247,7 +2250,7 @@ class APIRouter(routing.Router):
It will be added to the generated OpenAPI (e.g. visible at `/docs`). It will be added to the generated OpenAPI (e.g. visible at `/docs`).
""" """
), ),
] = "Successful Response", ] = None,
responses: Annotated[ responses: Annotated[
Optional[Dict[Union[int, str], Dict[str, Any]]], Optional[Dict[Union[int, str], Dict[str, Any]]],
Doc( Doc(
@ -2621,7 +2624,7 @@ class APIRouter(routing.Router):
), ),
] = None, ] = None,
response_description: Annotated[ response_description: Annotated[
str, Optional[str],
Doc( Doc(
""" """
The description for the default response. The description for the default response.
@ -2629,7 +2632,7 @@ class APIRouter(routing.Router):
It will be added to the generated OpenAPI (e.g. visible at `/docs`). It will be added to the generated OpenAPI (e.g. visible at `/docs`).
""" """
), ),
] = "Successful Response", ] = None,
responses: Annotated[ responses: Annotated[
Optional[Dict[Union[int, str], Dict[str, Any]]], Optional[Dict[Union[int, str], Dict[str, Any]]],
Doc( Doc(
@ -2998,7 +3001,7 @@ class APIRouter(routing.Router):
), ),
] = None, ] = None,
response_description: Annotated[ response_description: Annotated[
str, Optional[str],
Doc( Doc(
""" """
The description for the default response. The description for the default response.
@ -3006,7 +3009,7 @@ class APIRouter(routing.Router):
It will be added to the generated OpenAPI (e.g. visible at `/docs`). It will be added to the generated OpenAPI (e.g. visible at `/docs`).
""" """
), ),
] = "Successful Response", ] = None,
responses: Annotated[ responses: Annotated[
Optional[Dict[Union[int, str], Dict[str, Any]]], Optional[Dict[Union[int, str], Dict[str, Any]]],
Doc( Doc(
@ -3375,7 +3378,7 @@ class APIRouter(routing.Router):
), ),
] = None, ] = None,
response_description: Annotated[ response_description: Annotated[
str, Optional[str],
Doc( Doc(
""" """
The description for the default response. The description for the default response.
@ -3383,7 +3386,7 @@ class APIRouter(routing.Router):
It will be added to the generated OpenAPI (e.g. visible at `/docs`). It will be added to the generated OpenAPI (e.g. visible at `/docs`).
""" """
), ),
] = "Successful Response", ] = None,
responses: Annotated[ responses: Annotated[
Optional[Dict[Union[int, str], Dict[str, Any]]], Optional[Dict[Union[int, str], Dict[str, Any]]],
Doc( Doc(
@ -3757,7 +3760,7 @@ class APIRouter(routing.Router):
), ),
] = None, ] = None,
response_description: Annotated[ response_description: Annotated[
str, Optional[str],
Doc( Doc(
""" """
The description for the default response. The description for the default response.
@ -3765,7 +3768,7 @@ class APIRouter(routing.Router):
It will be added to the generated OpenAPI (e.g. visible at `/docs`). It will be added to the generated OpenAPI (e.g. visible at `/docs`).
""" """
), ),
] = "Successful Response", ] = None,
responses: Annotated[ responses: Annotated[
Optional[Dict[Union[int, str], Dict[str, Any]]], Optional[Dict[Union[int, str], Dict[str, Any]]],
Doc( Doc(
@ -4139,7 +4142,7 @@ class APIRouter(routing.Router):
), ),
] = None, ] = None,
response_description: Annotated[ response_description: Annotated[
str, Optional[str],
Doc( Doc(
""" """
The description for the default response. The description for the default response.
@ -4147,7 +4150,7 @@ class APIRouter(routing.Router):
It will be added to the generated OpenAPI (e.g. visible at `/docs`). It will be added to the generated OpenAPI (e.g. visible at `/docs`).
""" """
), ),
] = "Successful Response", ] = None,
responses: Annotated[ responses: Annotated[
Optional[Dict[Union[int, str], Dict[str, Any]]], Optional[Dict[Union[int, str], Dict[str, Any]]],
Doc( Doc(

1
pyproject.toml
View File

@ -46,6 +46,7 @@ dependencies = [
"starlette>=0.40.0,<0.47.0", "starlette>=0.40.0,<0.47.0",
"pydantic>=1.7.4,!=1.8,!=1.8.1,!=2.0.0,!=2.0.1,!=2.1.0,<3.0.0", "pydantic>=1.7.4,!=1.8,!=1.8.1,!=2.0.0,!=2.0.1,!=2.1.0,<3.0.0",
"typing-extensions>=4.8.0", "typing-extensions>=4.8.0",
"griffe>=1.7.0",
] ]
[project.urls] [project.urls]

Write Preview
Loading…
Cancel
Save