1f01ce9615
* Updated .py files with Optional tag (up to body_nested_models) * Update optionals * docs_src/ all updates, few I was unsure of * Updated markdown files with Optional param * es: Add Optional typing to index.md * Last of markdown files updated with Optional param * Update highlight lines * it: Add Optional typings * README.md: Update with Optional typings * Update more highlight increments * Update highlights * schema-extra-example.md: Update highlights * updating highlighting on website to reflect .py changes * Update highlighting for query-params & response-directly * Address PR comments * Get rid of unnecessary comment * ⏪ Revert Optional in Chinese docs as it probably also requires changes in text * 🎨 Apply format * ⏪ Revert modified example * ♻️ Simplify example in docs * 📝 Update OpenAPI callback example to use Optional * ✨ Add Optional types to tests * 📝 Update docs about query params, default to using Optional * 🎨 Update code examples line highlighting * 📝 Update nested models docs to use "type parameters" instead of "subtypes" * 📝 Add notes about FastAPI usage of None including: = None and = Query(None) and clarify relationship with Optional[str] * 📝 Add note about response_model_by_alias * ♻️ Simplify query param list example * 🔥 Remove test for removed example * ✅ Update test for updated example Co-authored-by: Christopher Nguyen <chrisngyn99@gmail.com> Co-authored-by: yk396 <yk396@cornell.edu> Co-authored-by: Kai Chen <kaichen120@gmail.com>
2.5 KiB
Schema Extra - Example
You can define extra information to go in JSON Schema.
A common use case is to add an example that will be shown in the docs.
There are several ways you can declare extra JSON Schema information.
Pydantic schema_extra
You can declare an example for a Pydantic model using Config and schema_extra, as described in Pydantic's docs: Schema customization:
{!../../../docs_src/schema_extra_example/tutorial001.py!}
That extra info will be added as-is to the output JSON Schema.
Field additional arguments
In Field, Path, Query, Body and others you'll see later, you can also declare extra info for the JSON Schema by passing any other arbitrary arguments to the function, for example, to add an example:
{!../../../docs_src/schema_extra_example/tutorial002.py!}
!!! warning Have in mind that those extra arguments passed won't add any validation, only annotation, for documentation purposes.
Body additional arguments
The same way you can pass extra info to Field, you can do the same with Path, Query, Body, etc.
For example, you can pass an example for a body request to Body:
{!../../../docs_src/schema_extra_example/tutorial003.py!}
Example in the docs UI
With any of the methods above it would look like this in the /docs:
Technical Details
About example vs examples...
JSON Schema defines a field examples in the most recent versions, but OpenAPI is based on an older version of JSON Schema that didn't have examples.
So, OpenAPI defined its own example for the same purpose (as example, not examples), and that's what is used by the docs UI (using Swagger UI).
So, although example is not part of JSON Schema, it is part of OpenAPI, and that's what will be used by the docs UI.
Other info
The same way, you could add your own custom extra info that would be added to the JSON Schema for each model, for example to customize a frontend user interface, etc.