openapi

18 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Pydantic v2 generates separate input/output OpenAPI schemas

Starting with Pydantic v2, FastAPI generates two JSON Schemas in OpenAPI for the same Pydantic model when used for both input and output, if the fields have default values. This results in more exact and correct OpenAPI documentation.

Model field requiredness differs between input and output schemas

For input schemas, a field with a default value is not required. For output schemas, a field with a default value is marked as required because it will always be present in the response, even if the value is None/null. This creates separate JSON Schemas: one for input and one for output.

Use case for disabling separate input/output schemas

The main use case for disabling separate input/output schemas is when you already have autogenerated client code or SDKs that you do not want to update yet. Setting `separate_input_output_schemas=False` keeps the schema the same for both input and output.

Output schema marks fields with defaults as required

In the output schema, fields with default values are marked as required with a red asterisk in the docs, because the field will always be present in the response. If no value is provided for that field, the default value will be returned (which may be None/null).

FastAPI automatic documentation URLs

FastAPI automatically provides two interactive API documentation interfaces: Swagger UI at http://127.0.0.1:8000/docs and ReDoc at http://127.0.0.1:8000/redoc. Both are generated from OpenAPI schema automatically.

Automatic response description in OpenAPI

OpenAPI requires that every path operation has a description of the response. If you do not provide one, FastAPI will automatically create one for 'Successful Response'.

OpenAPI Extensions with openapi_extra

Using openapi_extra, you can declare OpenAPI Extensions (vendor extensions prefixed with x-). These extensions will show up at the bottom of the specific path operation in automatic API docs and will be included in the OpenAPI schema at /openapi.json.

Custom OpenAPI schema without automatic validation

You can use openapi_extra to define custom OpenAPI request schemas without using FastAPI's automatic Pydantic validation. This allows you to read and validate requests with your own code while still documenting the expected schema in OpenAPI. For example, you could define a schema for request body content that is read as bytes instead of being parsed as JSON.

Custom OpenAPI content type with Pydantic schema

You can use openapi_extra with a Pydantic model to define the JSON Schema for custom content types in OpenAPI, even if the actual request data is not JSON. For example, you can declare the request content type as YAML in the OpenAPI schema while FastAPI reads the request body as bytes and you parse the YAML content manually, then validate it with a Pydantic model.

Custom operationId in OpenAPI with operation_id parameter

To set a custom operationId for a path operation in OpenAPI, use the operation_id parameter in the path operation decorator. The operationId must be unique for each operation.

Generate unique operationId from function names using generate_unique_id_function

To use path operation function names as operationIds, pass a custom generate_unique_id_function to the FastAPI constructor. This function receives each APIRoute and returns the operationId to use for that path operation. Each path operation function must have a unique name, even if in different modules.

Exclude path operation from OpenAPI schema with include_in_schema

To exclude a path operation from the generated OpenAPI schema and automatic documentation systems, use the include_in_schema parameter and set it to False in the path operation decorator.

Use form feed character to truncate docstring in OpenAPI

Add a \f character (escaped form feed) in a path operation function's docstring to truncate the output used for OpenAPI at that point. Content after the \f appears in the docstring but not in OpenAPI documentation, though other tools like Sphinx can use the rest.

Extend OpenAPI schema with openapi_extra parameter

Use the openapi_extra parameter in a path operation decorator to extend the OpenAPI schema for that operation. The dictionary in openapi_extra is deeply merged with the automatically generated OpenAPI schema for the path operation.

OpenAPI Extensions with openapi_extra

OpenAPI Extensions can be declared using openapi_extra parameter. Extensions appear at the bottom of the specific path operation in automatic documentation and in the /openapi.json endpoint with names prefixed by 'x-' (e.g., 'x-aperture-labs-portal').

Custom OpenAPI request body schema without Pydantic parsing

Use openapi_extra to declare an expected request body schema in OpenAPI while reading the request directly as bytes without FastAPI's automatic parsing. This allows defining the schema independently from automatic validation.

Custom content type in OpenAPI with openapi_extra

Use openapi_extra to declare custom content types (such as YAML instead of JSON) in the OpenAPI schema. The request body can be read as bytes and processed manually while still documenting the expected schema in OpenAPI.

OpenAPI Operation Object definition

In the OpenAPI specification, the Operation Object contains all information about a path operation and is used to generate automatic documentation. It includes tags, parameters, requestBody, responses, and other metadata that FastAPI generates automatically and can be extended.

Give your agent this brain