[{"data":1,"prerenderedAt":2086},["ShallowReactive",2],{"nav":3,"page-\u002Fadvanced-pydantic-validation-serialization\u002Fjson-schema-customization\u002Fexamples-in-openapi-schema\u002F":580,"surround-\u002Fadvanced-pydantic-validation-serialization\u002Fjson-schema-customization\u002Fexamples-in-openapi-schema\u002F":2085},[4,186,386],{"title":5,"path":6,"stem":7,"children":8},"Advanced Pydantic Validation Serialization","\u002Fadvanced-pydantic-validation-serialization","advanced-pydantic-validation-serialization",[9,12,42,66,90,114,150,174],{"title":10,"path":6,"stem":11},"Advanced Pydantic Validation and Serialization","advanced-pydantic-validation-serialization\u002Findex",{"title":13,"path":14,"stem":15,"children":16},"Custom Validators and Field Constraints in Pydantic","\u002Fadvanced-pydantic-validation-serialization\u002Fcustom-validators-field-constraints","advanced-pydantic-validation-serialization\u002Fcustom-validators-field-constraints\u002Findex",[17,18,24,30,36],{"title":13,"path":14,"stem":15},{"title":19,"path":20,"stem":21,"children":22},"Before, After and Wrap Validators in Pydantic v2","\u002Fadvanced-pydantic-validation-serialization\u002Fcustom-validators-field-constraints\u002Fbefore-after-and-wrap-validators","advanced-pydantic-validation-serialization\u002Fcustom-validators-field-constraints\u002Fbefore-after-and-wrap-validators\u002Findex",[23],{"title":19,"path":20,"stem":21},{"title":25,"path":26,"stem":27,"children":28},"Creating Reusable Custom Validators in Pydantic","\u002Fadvanced-pydantic-validation-serialization\u002Fcustom-validators-field-constraints\u002Fcreating-reusable-custom-validators-in-pydantic","advanced-pydantic-validation-serialization\u002Fcustom-validators-field-constraints\u002Fcreating-reusable-custom-validators-in-pydantic\u002Findex",[29],{"title":25,"path":26,"stem":27},{"title":31,"path":32,"stem":33,"children":34},"Cross-Field Validation Patterns in Pydantic v2","\u002Fadvanced-pydantic-validation-serialization\u002Fcustom-validators-field-constraints\u002Fcross-field-validation-patterns","advanced-pydantic-validation-serialization\u002Fcustom-validators-field-constraints\u002Fcross-field-validation-patterns\u002Findex",[35],{"title":31,"path":32,"stem":33},{"title":37,"path":38,"stem":39,"children":40},"Pydantic v2 Async Custom Validator: What to Do Instead","\u002Fadvanced-pydantic-validation-serialization\u002Fcustom-validators-field-constraints\u002Fpydantic-v2-async-custom-validator","advanced-pydantic-validation-serialization\u002Fcustom-validators-field-constraints\u002Fpydantic-v2-async-custom-validator\u002Findex",[41],{"title":37,"path":38,"stem":39},{"title":43,"path":44,"stem":45,"children":46},"JSON Schema Customization in Pydantic and FastAPI","\u002Fadvanced-pydantic-validation-serialization\u002Fjson-schema-customization","advanced-pydantic-validation-serialization\u002Fjson-schema-customization\u002Findex",[47,48,54,60],{"title":43,"path":44,"stem":45},{"title":49,"path":50,"stem":51,"children":52},"Customizing OpenAPI Schema Generation in FastAPI","\u002Fadvanced-pydantic-validation-serialization\u002Fjson-schema-customization\u002Fcustomizing-openapi-schema-generation-in-fastapi","advanced-pydantic-validation-serialization\u002Fjson-schema-customization\u002Fcustomizing-openapi-schema-generation-in-fastapi\u002Findex",[53],{"title":49,"path":50,"stem":51},{"title":55,"path":56,"stem":57,"children":58},"Discriminated Unions in OpenAPI with Pydantic","\u002Fadvanced-pydantic-validation-serialization\u002Fjson-schema-customization\u002Fdiscriminated-unions-in-openapi","advanced-pydantic-validation-serialization\u002Fjson-schema-customization\u002Fdiscriminated-unions-in-openapi\u002Findex",[59],{"title":55,"path":56,"stem":57},{"title":61,"path":62,"stem":63,"children":64},"Examples in the OpenAPI Schema with FastAPI","\u002Fadvanced-pydantic-validation-serialization\u002Fjson-schema-customization\u002Fexamples-in-openapi-schema","advanced-pydantic-validation-serialization\u002Fjson-schema-customization\u002Fexamples-in-openapi-schema\u002Findex",[65],{"title":61,"path":62,"stem":63},{"title":67,"path":68,"stem":69,"children":70},"Nested Model Serialization in FastAPI","\u002Fadvanced-pydantic-validation-serialization\u002Fnested-model-serialization","advanced-pydantic-validation-serialization\u002Fnested-model-serialization\u002Findex",[71,72,78,84],{"title":67,"path":68,"stem":69},{"title":73,"path":74,"stem":75,"children":76},"Excluding Fields Per Endpoint in FastAPI","\u002Fadvanced-pydantic-validation-serialization\u002Fnested-model-serialization\u002Fexcluding-fields-per-endpoint","advanced-pydantic-validation-serialization\u002Fnested-model-serialization\u002Fexcluding-fields-per-endpoint\u002Findex",[77],{"title":73,"path":74,"stem":75},{"title":79,"path":80,"stem":81,"children":82},"Handling Deeply Nested JSON Models Efficiently","\u002Fadvanced-pydantic-validation-serialization\u002Fnested-model-serialization\u002Fhandling-deeply-nested-json-models-efficiently","advanced-pydantic-validation-serialization\u002Fnested-model-serialization\u002Fhandling-deeply-nested-json-models-efficiently\u002Findex",[83],{"title":79,"path":80,"stem":81},{"title":85,"path":86,"stem":87,"children":88},"Self-Referencing and Recursive Models in Pydantic v2","\u002Fadvanced-pydantic-validation-serialization\u002Fnested-model-serialization\u002Fself-referencing-and-recursive-models","advanced-pydantic-validation-serialization\u002Fnested-model-serialization\u002Fself-referencing-and-recursive-models\u002Findex",[89],{"title":85,"path":86,"stem":87},{"title":91,"path":92,"stem":93,"children":94},"Performance Optimization for Pydantic Models in FastAPI","\u002Fadvanced-pydantic-validation-serialization\u002Fperformance-optimization-for-models","advanced-pydantic-validation-serialization\u002Fperformance-optimization-for-models\u002Findex",[95,96,102,108],{"title":91,"path":92,"stem":93},{"title":97,"path":98,"stem":99,"children":100},"model_construct and When to Skip Validation in Pydantic","\u002Fadvanced-pydantic-validation-serialization\u002Fperformance-optimization-for-models\u002Fmodel-construct-when-to-skip-validation","advanced-pydantic-validation-serialization\u002Fperformance-optimization-for-models\u002Fmodel-construct-when-to-skip-validation\u002Findex",[101],{"title":97,"path":98,"stem":99},{"title":103,"path":104,"stem":105,"children":106},"Pydantic Model Serialization Performance in FastAPI","\u002Fadvanced-pydantic-validation-serialization\u002Fperformance-optimization-for-models\u002Fpydantic-model-serialization-performance","advanced-pydantic-validation-serialization\u002Fperformance-optimization-for-models\u002Fpydantic-model-serialization-performance\u002Findex",[107],{"title":103,"path":104,"stem":105},{"title":109,"path":110,"stem":111,"children":112},"TypeAdapter for Non-Model Types in Pydantic","\u002Fadvanced-pydantic-validation-serialization\u002Fperformance-optimization-for-models\u002Ftypeadapter-for-non-model-types","advanced-pydantic-validation-serialization\u002Fperformance-optimization-for-models\u002Ftypeadapter-for-non-model-types\u002Findex",[113],{"title":109,"path":110,"stem":111},{"title":115,"path":116,"stem":117,"children":118},"Pydantic V2 Migration Guide for FastAPI","\u002Fadvanced-pydantic-validation-serialization\u002Fpydantic-v2-migration-guide","advanced-pydantic-validation-serialization\u002Fpydantic-v2-migration-guide\u002Findex",[119,120,126,132,138,144],{"title":115,"path":116,"stem":117},{"title":121,"path":122,"stem":123,"children":124},"Migrate @validator to @field_validator in Pydantic v2","\u002Fadvanced-pydantic-validation-serialization\u002Fpydantic-v2-migration-guide\u002Fmigrate-validator-to-field-validator","advanced-pydantic-validation-serialization\u002Fpydantic-v2-migration-guide\u002Fmigrate-validator-to-field-validator\u002Findex",[125],{"title":121,"path":122,"stem":123},{"title":127,"path":128,"stem":129,"children":130},"Migrating from Pydantic v1 to v2 Without Breaking APIs","\u002Fadvanced-pydantic-validation-serialization\u002Fpydantic-v2-migration-guide\u002Fmigrating-from-pydantic-v1-to-v2-without-breaking-apis","advanced-pydantic-validation-serialization\u002Fpydantic-v2-migration-guide\u002Fmigrating-from-pydantic-v1-to-v2-without-breaking-apis\u002Findex",[131],{"title":127,"path":128,"stem":129},{"title":133,"path":134,"stem":135,"children":136},"model_config vs class Config in Pydantic v2","\u002Fadvanced-pydantic-validation-serialization\u002Fpydantic-v2-migration-guide\u002Fmodel-config-vs-class-config","advanced-pydantic-validation-serialization\u002Fpydantic-v2-migration-guide\u002Fmodel-config-vs-class-config\u002Findex",[137],{"title":133,"path":134,"stem":135},{"title":139,"path":140,"stem":141,"children":142},"Replacing json_encoders with field_serializer in Pydantic v2","\u002Fadvanced-pydantic-validation-serialization\u002Fpydantic-v2-migration-guide\u002Freplacing-json-encoders-with-field-serializer","advanced-pydantic-validation-serialization\u002Fpydantic-v2-migration-guide\u002Freplacing-json-encoders-with-field-serializer\u002Findex",[143],{"title":139,"path":140,"stem":141},{"title":145,"path":146,"stem":147,"children":148},"Migrating @root_validator to @model_validator in Pydantic v2","\u002Fadvanced-pydantic-validation-serialization\u002Fpydantic-v2-migration-guide\u002Froot-validator-to-model-validator","advanced-pydantic-validation-serialization\u002Fpydantic-v2-migration-guide\u002Froot-validator-to-model-validator\u002Findex",[149],{"title":145,"path":146,"stem":147},{"title":151,"path":152,"stem":153,"children":154},"Request Validation Patterns in FastAPI","\u002Fadvanced-pydantic-validation-serialization\u002Frequest-validation-patterns","advanced-pydantic-validation-serialization\u002Frequest-validation-patterns\u002Findex",[155,156,162,168],{"title":151,"path":152,"stem":153},{"title":157,"path":158,"stem":159,"children":160},"Optional vs Nullable Fields in Pydantic and FastAPI","\u002Fadvanced-pydantic-validation-serialization\u002Frequest-validation-patterns\u002Foptional-vs-nullable-fields","advanced-pydantic-validation-serialization\u002Frequest-validation-patterns\u002Foptional-vs-nullable-fields\u002Findex",[161],{"title":157,"path":158,"stem":159},{"title":163,"path":164,"stem":165,"children":166},"Query, Path and Body Parameter Validation in FastAPI","\u002Fadvanced-pydantic-validation-serialization\u002Frequest-validation-patterns\u002Fquery-path-and-body-parameter-validation","advanced-pydantic-validation-serialization\u002Frequest-validation-patterns\u002Fquery-path-and-body-parameter-validation\u002Findex",[167],{"title":163,"path":164,"stem":165},{"title":169,"path":170,"stem":171,"children":172},"Validating File Uploads and Forms in FastAPI","\u002Fadvanced-pydantic-validation-serialization\u002Frequest-validation-patterns\u002Fvalidating-file-uploads-and-forms","advanced-pydantic-validation-serialization\u002Frequest-validation-patterns\u002Fvalidating-file-uploads-and-forms\u002Findex",[173],{"title":169,"path":170,"stem":171},{"title":175,"path":176,"stem":177,"children":178},"Type Hinting and IDE Integration in FastAPI","\u002Fadvanced-pydantic-validation-serialization\u002Ftype-hinting-ide-integration","advanced-pydantic-validation-serialization\u002Ftype-hinting-ide-integration\u002Findex",[179,180],{"title":175,"path":176,"stem":177},{"title":181,"path":182,"stem":183,"children":184},"Annotated Dependencies and Reusable Types in FastAPI","\u002Fadvanced-pydantic-validation-serialization\u002Ftype-hinting-ide-integration\u002Fannotated-dependencies-and-reusable-types","advanced-pydantic-validation-serialization\u002Ftype-hinting-ide-integration\u002Fannotated-dependencies-and-reusable-types\u002Findex",[185],{"title":181,"path":182,"stem":183},{"title":187,"path":188,"stem":189,"children":190},"Async Background Tasks Observability","\u002Fasync-background-tasks-observability","async-background-tasks-observability",[191,194,224,254,284,308,338,362],{"title":192,"path":188,"stem":193},"Async, Background Tasks, and Observability in FastAPI","async-background-tasks-observability\u002Findex",{"title":195,"path":196,"stem":197,"children":198},"Async Correctness and Concurrency in FastAPI","\u002Fasync-background-tasks-observability\u002Fasync-correctness-concurrency","async-background-tasks-observability\u002Fasync-correctness-concurrency\u002Findex",[199,200,206,212,218],{"title":195,"path":196,"stem":197},{"title":201,"path":202,"stem":203,"children":204},"Concurrent Requests with asyncio.gather in FastAPI","\u002Fasync-background-tasks-observability\u002Fasync-correctness-concurrency\u002Fconcurrent-requests-with-asyncio-gather","async-background-tasks-observability\u002Fasync-correctness-concurrency\u002Fconcurrent-requests-with-asyncio-gather\u002Findex",[205],{"title":201,"path":202,"stem":203},{"title":207,"path":208,"stem":209,"children":210},"FastAPI async def vs def: Performance and When to Use Each","\u002Fasync-background-tasks-observability\u002Fasync-correctness-concurrency\u002Ffastapi-async-def-vs-def-performance","async-background-tasks-observability\u002Fasync-correctness-concurrency\u002Ffastapi-async-def-vs-def-performance\u002Findex",[211],{"title":207,"path":208,"stem":209},{"title":213,"path":214,"stem":215,"children":216},"Fixing Blocking Calls in Async FastAPI Routes","\u002Fasync-background-tasks-observability\u002Fasync-correctness-concurrency\u002Ffixing-blocking-calls-in-async-routes","async-background-tasks-observability\u002Fasync-correctness-concurrency\u002Ffixing-blocking-calls-in-async-routes\u002Findex",[217],{"title":213,"path":214,"stem":215},{"title":219,"path":220,"stem":221,"children":222},"Running Sync Code in a Threadpool in FastAPI","\u002Fasync-background-tasks-observability\u002Fasync-correctness-concurrency\u002Frunning-sync-code-in-a-threadpool","async-background-tasks-observability\u002Fasync-correctness-concurrency\u002Frunning-sync-code-in-a-threadpool\u002Findex",[223],{"title":219,"path":220,"stem":221},{"title":225,"path":226,"stem":227,"children":228},"Async Database Sessions in FastAPI","\u002Fasync-background-tasks-observability\u002Fasync-database-sessions","async-background-tasks-observability\u002Fasync-database-sessions\u002Findex",[229,230,236,242,248],{"title":225,"path":226,"stem":227},{"title":231,"path":232,"stem":233,"children":234},"Async SQLAlchemy Session per Request in FastAPI","\u002Fasync-background-tasks-observability\u002Fasync-database-sessions\u002Fasync-sqlalchemy-session-per-request","async-background-tasks-observability\u002Fasync-database-sessions\u002Fasync-sqlalchemy-session-per-request\u002Findex",[235],{"title":231,"path":232,"stem":233},{"title":237,"path":238,"stem":239,"children":240},"Fixing asyncpg Connection Pool Exhaustion in FastAPI","\u002Fasync-background-tasks-observability\u002Fasync-database-sessions\u002Ffixing-asyncpg-pool-exhaustion","async-background-tasks-observability\u002Fasync-database-sessions\u002Ffixing-asyncpg-pool-exhaustion\u002Findex",[241],{"title":237,"path":238,"stem":239},{"title":243,"path":244,"stem":245,"children":246},"Testing with Async Database Fixtures in FastAPI","\u002Fasync-background-tasks-observability\u002Fasync-database-sessions\u002Ftesting-with-async-database-fixtures","async-background-tasks-observability\u002Fasync-database-sessions\u002Ftesting-with-async-database-fixtures\u002Findex",[247],{"title":243,"path":244,"stem":245},{"title":249,"path":250,"stem":251,"children":252},"Transaction Management and Rollback in FastAPI","\u002Fasync-background-tasks-observability\u002Fasync-database-sessions\u002Ftransaction-management-and-rollback","async-background-tasks-observability\u002Fasync-database-sessions\u002Ftransaction-management-and-rollback\u002Findex",[253],{"title":249,"path":250,"stem":251},{"title":255,"path":256,"stem":257,"children":258},"Background Task Processing in FastAPI","\u002Fasync-background-tasks-observability\u002Fbackground-task-processing","async-background-tasks-observability\u002Fbackground-task-processing\u002Findex",[259,260,266,272,278],{"title":255,"path":256,"stem":257},{"title":261,"path":262,"stem":263,"children":264},"FastAPI BackgroundTasks vs Celery vs ARQ","\u002Fasync-background-tasks-observability\u002Fbackground-task-processing\u002Ffastapi-backgroundtasks-vs-celery-vs-arq","async-background-tasks-observability\u002Fbackground-task-processing\u002Ffastapi-backgroundtasks-vs-celery-vs-arq\u002Findex",[265],{"title":261,"path":262,"stem":263},{"title":267,"path":268,"stem":269,"children":270},"Retry and Idempotency for FastAPI Background Tasks","\u002Fasync-background-tasks-observability\u002Fbackground-task-processing\u002Fretry-and-idempotency-for-tasks","async-background-tasks-observability\u002Fbackground-task-processing\u002Fretry-and-idempotency-for-tasks\u002Findex",[271],{"title":267,"path":268,"stem":269},{"title":273,"path":274,"stem":275,"children":276},"Running ARQ Workers with FastAPI","\u002Fasync-background-tasks-observability\u002Fbackground-task-processing\u002Frunning-arq-workers-with-fastapi","async-background-tasks-observability\u002Fbackground-task-processing\u002Frunning-arq-workers-with-fastapi\u002Findex",[277],{"title":273,"path":274,"stem":275},{"title":279,"path":280,"stem":281,"children":282},"When FastAPI BackgroundTasks Silently Fails","\u002Fasync-background-tasks-observability\u002Fbackground-task-processing\u002Fwhen-backgroundtasks-silently-fails","async-background-tasks-observability\u002Fbackground-task-processing\u002Fwhen-backgroundtasks-silently-fails\u002Findex",[283],{"title":279,"path":280,"stem":281},{"title":285,"path":286,"stem":287,"children":288},"Caching Strategies in FastAPI","\u002Fasync-background-tasks-observability\u002Fcaching-strategies","async-background-tasks-observability\u002Fcaching-strategies\u002Findex",[289,290,296,302],{"title":285,"path":286,"stem":287},{"title":291,"path":292,"stem":293,"children":294},"Cache Invalidation Patterns in FastAPI","\u002Fasync-background-tasks-observability\u002Fcaching-strategies\u002Fcache-invalidation-patterns-in-fastapi","async-background-tasks-observability\u002Fcaching-strategies\u002Fcache-invalidation-patterns-in-fastapi\u002Findex",[295],{"title":291,"path":292,"stem":293},{"title":297,"path":298,"stem":299,"children":300},"Caching Dependency Results in FastAPI","\u002Fasync-background-tasks-observability\u002Fcaching-strategies\u002Fcaching-dependency-results","async-background-tasks-observability\u002Fcaching-strategies\u002Fcaching-dependency-results\u002Findex",[301],{"title":297,"path":298,"stem":299},{"title":303,"path":304,"stem":305,"children":306},"Redis Response Caching in FastAPI","\u002Fasync-background-tasks-observability\u002Fcaching-strategies\u002Fredis-response-caching-in-fastapi","async-background-tasks-observability\u002Fcaching-strategies\u002Fredis-response-caching-in-fastapi\u002Findex",[307],{"title":303,"path":304,"stem":305},{"title":309,"path":310,"stem":311,"children":312},"Observability and Tracing in FastAPI","\u002Fasync-background-tasks-observability\u002Fobservability-and-tracing","async-background-tasks-observability\u002Fobservability-and-tracing\u002Findex",[313,314,320,326,332],{"title":309,"path":310,"stem":311},{"title":315,"path":316,"stem":317,"children":318},"Correlating Logs, Traces and Errors in FastAPI","\u002Fasync-background-tasks-observability\u002Fobservability-and-tracing\u002Fcorrelating-logs-traces-and-errors","async-background-tasks-observability\u002Fobservability-and-tracing\u002Fcorrelating-logs-traces-and-errors\u002Findex",[319],{"title":315,"path":316,"stem":317},{"title":321,"path":322,"stem":323,"children":324},"Instrumenting FastAPI with OpenTelemetry","\u002Fasync-background-tasks-observability\u002Fobservability-and-tracing\u002Finstrumenting-fastapi-with-opentelemetry","async-background-tasks-observability\u002Fobservability-and-tracing\u002Finstrumenting-fastapi-with-opentelemetry\u002Findex",[325],{"title":321,"path":322,"stem":323},{"title":327,"path":328,"stem":329,"children":330},"Prometheus Metrics for FastAPI","\u002Fasync-background-tasks-observability\u002Fobservability-and-tracing\u002Fprometheus-metrics-for-fastapi","async-background-tasks-observability\u002Fobservability-and-tracing\u002Fprometheus-metrics-for-fastapi\u002Findex",[331],{"title":327,"path":328,"stem":329},{"title":333,"path":334,"stem":335,"children":336},"Structured JSON Logging with Request IDs in FastAPI","\u002Fasync-background-tasks-observability\u002Fobservability-and-tracing\u002Fstructured-json-logging-with-request-ids","async-background-tasks-observability\u002Fobservability-and-tracing\u002Fstructured-json-logging-with-request-ids\u002Findex",[337],{"title":333,"path":334,"stem":335},{"title":339,"path":340,"stem":341,"children":342},"Rate Limiting and Throttling in FastAPI","\u002Fasync-background-tasks-observability\u002Frate-limiting-throttling","async-background-tasks-observability\u002Frate-limiting-throttling\u002Findex",[343,344,350,356],{"title":339,"path":340,"stem":341},{"title":345,"path":346,"stem":347,"children":348},"FastAPI Rate Limiting with Redis and SlowAPI","\u002Fasync-background-tasks-observability\u002Frate-limiting-throttling\u002Ffastapi-rate-limiting-with-redis-slowapi","async-background-tasks-observability\u002Frate-limiting-throttling\u002Ffastapi-rate-limiting-with-redis-slowapi\u002Findex",[349],{"title":345,"path":346,"stem":347},{"title":351,"path":352,"stem":353,"children":354},"Per-User Token Bucket Throttling in FastAPI","\u002Fasync-background-tasks-observability\u002Frate-limiting-throttling\u002Fper-user-token-bucket-throttling","async-background-tasks-observability\u002Frate-limiting-throttling\u002Fper-user-token-bucket-throttling\u002Findex",[355],{"title":351,"path":352,"stem":353},{"title":357,"path":358,"stem":359,"children":360},"Rate Limit Headers and 429 Responses in FastAPI","\u002Fasync-background-tasks-observability\u002Frate-limiting-throttling\u002Frate-limit-headers-and-429-responses","async-background-tasks-observability\u002Frate-limiting-throttling\u002Frate-limit-headers-and-429-responses\u002Findex",[361],{"title":357,"path":358,"stem":359},{"title":363,"path":364,"stem":365,"children":366},"Testing FastAPI Applications","\u002Fasync-background-tasks-observability\u002Ftesting-fastapi-applications","async-background-tasks-observability\u002Ftesting-fastapi-applications\u002Findex",[367,368,374,380],{"title":363,"path":364,"stem":365},{"title":369,"path":370,"stem":371,"children":372},"Mocking External Services in FastAPI Tests","\u002Fasync-background-tasks-observability\u002Ftesting-fastapi-applications\u002Fmocking-external-services-in-tests","async-background-tasks-observability\u002Ftesting-fastapi-applications\u002Fmocking-external-services-in-tests\u002Findex",[373],{"title":369,"path":370,"stem":371},{"title":375,"path":376,"stem":377,"children":378},"TestClient vs httpx AsyncClient in FastAPI","\u002Fasync-background-tasks-observability\u002Ftesting-fastapi-applications\u002Ftestclient-vs-httpx-asyncclient","async-background-tasks-observability\u002Ftesting-fastapi-applications\u002Ftestclient-vs-httpx-asyncclient\u002Findex",[379],{"title":375,"path":376,"stem":377},{"title":381,"path":382,"stem":383,"children":384},"Testing Async FastAPI Endpoints with pytest-asyncio","\u002Fasync-background-tasks-observability\u002Ftesting-fastapi-applications\u002Ftesting-async-endpoints-with-pytest-asyncio","async-background-tasks-observability\u002Ftesting-fastapi-applications\u002Ftesting-async-endpoints-with-pytest-asyncio\u002Findex",[385],{"title":381,"path":382,"stem":383},{"title":387,"path":388,"stem":389,"children":390},"Core Architecture Routing Patterns","\u002Fcore-architecture-routing-patterns","core-architecture-routing-patterns",[391,394,412,436,472,496,526,556],{"title":392,"path":388,"stem":393},"FastAPI Core Architecture and Routing Patterns","core-architecture-routing-patterns\u002Findex",{"title":395,"path":396,"stem":397,"children":398},"Application Factory Patterns in FastAPI","\u002Fcore-architecture-routing-patterns\u002Fapplication-factory-patterns","core-architecture-routing-patterns\u002Fapplication-factory-patterns\u002Findex",[399,400,406],{"title":395,"path":396,"stem":397},{"title":401,"path":402,"stem":403,"children":404},"FastAPI App Factory Pattern for Testing and Deployment","\u002Fcore-architecture-routing-patterns\u002Fapplication-factory-patterns\u002Ffastapi-app-factory-pattern-for-testing-and-deployment","core-architecture-routing-patterns\u002Fapplication-factory-patterns\u002Ffastapi-app-factory-pattern-for-testing-and-deployment\u002Findex",[405],{"title":401,"path":402,"stem":403},{"title":407,"path":408,"stem":409,"children":410},"Lifespan Events vs Startup and Shutdown in FastAPI","\u002Fcore-architecture-routing-patterns\u002Fapplication-factory-patterns\u002Flifespan-events-vs-startup-shutdown","core-architecture-routing-patterns\u002Fapplication-factory-patterns\u002Flifespan-events-vs-startup-shutdown\u002Findex",[411],{"title":407,"path":408,"stem":409},{"title":413,"path":414,"stem":415,"children":416},"Configuration Management in FastAPI","\u002Fcore-architecture-routing-patterns\u002Fconfiguration-management","core-architecture-routing-patterns\u002Fconfiguration-management\u002Findex",[417,418,424,430],{"title":413,"path":414,"stem":415},{"title":419,"path":420,"stem":421,"children":422},"Managing Environment Variables with Pydantic Settings","\u002Fcore-architecture-routing-patterns\u002Fconfiguration-management\u002Fmanaging-environment-variables-with-pydantic-settings","core-architecture-routing-patterns\u002Fconfiguration-management\u002Fmanaging-environment-variables-with-pydantic-settings\u002Findex",[423],{"title":419,"path":420,"stem":421},{"title":425,"path":426,"stem":427,"children":428},"Pydantic Settings vs Dynaconf vs python-decouple","\u002Fcore-architecture-routing-patterns\u002Fconfiguration-management\u002Fpydantic-settings-vs-dynaconf-vs-python-decouple","core-architecture-routing-patterns\u002Fconfiguration-management\u002Fpydantic-settings-vs-dynaconf-vs-python-decouple\u002Findex",[429],{"title":425,"path":426,"stem":427},{"title":431,"path":432,"stem":433,"children":434},"Secrets and .env Files Per Environment in FastAPI","\u002Fcore-architecture-routing-patterns\u002Fconfiguration-management\u002Fsecrets-and-env-files-per-environment","core-architecture-routing-patterns\u002Fconfiguration-management\u002Fsecrets-and-env-files-per-environment\u002Findex",[435],{"title":431,"path":432,"stem":433},{"title":437,"path":438,"stem":439,"children":440},"Dependency Injection Strategies in FastAPI","\u002Fcore-architecture-routing-patterns\u002Fdependency-injection-strategies","core-architecture-routing-patterns\u002Fdependency-injection-strategies\u002Findex",[441,442,448,454,460,466],{"title":437,"path":438,"stem":439},{"title":443,"path":444,"stem":445,"children":446},"Best Practices for FastAPI Dependency Injection","\u002Fcore-architecture-routing-patterns\u002Fdependency-injection-strategies\u002Fbest-practices-for-fastapi-dependency-injection","core-architecture-routing-patterns\u002Fdependency-injection-strategies\u002Fbest-practices-for-fastapi-dependency-injection\u002Findex",[447],{"title":443,"path":444,"stem":445},{"title":449,"path":450,"stem":451,"children":452},"Dependency Caching and use_cache in FastAPI","\u002Fcore-architecture-routing-patterns\u002Fdependency-injection-strategies\u002Fdependency-caching-and-use-cache","core-architecture-routing-patterns\u002Fdependency-injection-strategies\u002Fdependency-caching-and-use-cache\u002Findex",[453],{"title":449,"path":450,"stem":451},{"title":455,"path":456,"stem":457,"children":458},"Fixing FastAPI Dependency Injection Circular Imports","\u002Fcore-architecture-routing-patterns\u002Fdependency-injection-strategies\u002Ffastapi-dependency-injection-circular-import-fix","core-architecture-routing-patterns\u002Fdependency-injection-strategies\u002Ffastapi-dependency-injection-circular-import-fix\u002Findex",[459],{"title":455,"path":456,"stem":457},{"title":461,"path":462,"stem":463,"children":464},"Overriding Dependencies in FastAPI Tests","\u002Fcore-architecture-routing-patterns\u002Fdependency-injection-strategies\u002Foverriding-dependencies-in-tests","core-architecture-routing-patterns\u002Fdependency-injection-strategies\u002Foverriding-dependencies-in-tests\u002Findex",[465],{"title":461,"path":462,"stem":463},{"title":467,"path":468,"stem":469,"children":470},"Yield Dependencies and Cleanup Order in FastAPI","\u002Fcore-architecture-routing-patterns\u002Fdependency-injection-strategies\u002Fyield-dependencies-and-cleanup-order","core-architecture-routing-patterns\u002Fdependency-injection-strategies\u002Fyield-dependencies-and-cleanup-order\u002Findex",[471],{"title":467,"path":468,"stem":469},{"title":473,"path":474,"stem":475,"children":476},"Error Handling and Global Exceptions in FastAPI","\u002Fcore-architecture-routing-patterns\u002Ferror-handling-global-exceptions","core-architecture-routing-patterns\u002Ferror-handling-global-exceptions\u002Findex",[477,478,484,490],{"title":473,"path":474,"stem":475},{"title":479,"path":480,"stem":481,"children":482},"Customising Validation Error Responses in FastAPI","\u002Fcore-architecture-routing-patterns\u002Ferror-handling-global-exceptions\u002Fcustomising-validation-error-responses","core-architecture-routing-patterns\u002Ferror-handling-global-exceptions\u002Fcustomising-validation-error-responses\u002Findex",[483],{"title":479,"path":480,"stem":481},{"title":485,"path":486,"stem":487,"children":488},"Global Exception Handlers for Consistent API Responses","\u002Fcore-architecture-routing-patterns\u002Ferror-handling-global-exceptions\u002Fglobal-exception-handlers-for-consistent-api-responses","core-architecture-routing-patterns\u002Ferror-handling-global-exceptions\u002Fglobal-exception-handlers-for-consistent-api-responses\u002Findex",[489],{"title":485,"path":486,"stem":487},{"title":491,"path":492,"stem":493,"children":494},"HTTPException vs Custom Exception Classes in FastAPI","\u002Fcore-architecture-routing-patterns\u002Ferror-handling-global-exceptions\u002Fhttpexception-vs-custom-exception-classes","core-architecture-routing-patterns\u002Ferror-handling-global-exceptions\u002Fhttpexception-vs-custom-exception-classes\u002Findex",[495],{"title":491,"path":492,"stem":493},{"title":497,"path":498,"stem":499,"children":500},"Middleware Implementation in FastAPI","\u002Fcore-architecture-routing-patterns\u002Fmiddleware-implementation","core-architecture-routing-patterns\u002Fmiddleware-implementation\u002Findex",[501,502,508,514,520],{"title":497,"path":498,"stem":499},{"title":503,"path":504,"stem":505,"children":506},"CORS Middleware Configuration in FastAPI","\u002Fcore-architecture-routing-patterns\u002Fmiddleware-implementation\u002Fcors-middleware-configuration","core-architecture-routing-patterns\u002Fmiddleware-implementation\u002Fcors-middleware-configuration\u002Findex",[507],{"title":503,"path":504,"stem":505},{"title":509,"path":510,"stem":511,"children":512},"Implementing Custom Middleware for Request Tracing","\u002Fcore-architecture-routing-patterns\u002Fmiddleware-implementation\u002Fimplementing-custom-middleware-for-request-tracing","core-architecture-routing-patterns\u002Fmiddleware-implementation\u002Fimplementing-custom-middleware-for-request-tracing\u002Findex",[513],{"title":509,"path":510,"stem":511},{"title":515,"path":516,"stem":517,"children":518},"Middleware Execution Order in FastAPI","\u002Fcore-architecture-routing-patterns\u002Fmiddleware-implementation\u002Fmiddleware-execution-order","core-architecture-routing-patterns\u002Fmiddleware-implementation\u002Fmiddleware-execution-order\u002Findex",[519],{"title":515,"path":516,"stem":517},{"title":521,"path":522,"stem":523,"children":524},"Middleware vs Dependencies: When to Use Which","\u002Fcore-architecture-routing-patterns\u002Fmiddleware-implementation\u002Fmiddleware-vs-dependencies-when-to-use-which","core-architecture-routing-patterns\u002Fmiddleware-implementation\u002Fmiddleware-vs-dependencies-when-to-use-which\u002Findex",[525],{"title":521,"path":522,"stem":523},{"title":527,"path":528,"stem":529,"children":530},"Modular Router Organization in FastAPI","\u002Fcore-architecture-routing-patterns\u002Fmodular-router-organization","core-architecture-routing-patterns\u002Fmodular-router-organization\u002Findex",[531,532,538,544,550],{"title":527,"path":528,"stem":529},{"title":533,"path":534,"stem":535,"children":536},"APIRouter Prefix vs Sub-Application Mounting in FastAPI","\u002Fcore-architecture-routing-patterns\u002Fmodular-router-organization\u002Fapirouter-prefix-vs-sub-application-mounting","core-architecture-routing-patterns\u002Fmodular-router-organization\u002Fapirouter-prefix-vs-sub-application-mounting\u002Findex",[537],{"title":533,"path":534,"stem":535},{"title":539,"path":540,"stem":541,"children":542},"How to Structure Large FastAPI Projects for Scale","\u002Fcore-architecture-routing-patterns\u002Fmodular-router-organization\u002Fhow-to-structure-large-fastapi-projects-for-scale","core-architecture-routing-patterns\u002Fmodular-router-organization\u002Fhow-to-structure-large-fastapi-projects-for-scale\u002Findex",[543],{"title":539,"path":540,"stem":541},{"title":545,"path":546,"stem":547,"children":548},"Router Tags and OpenAPI Grouping in FastAPI","\u002Fcore-architecture-routing-patterns\u002Fmodular-router-organization\u002Frouter-tags-and-openapi-grouping","core-architecture-routing-patterns\u002Fmodular-router-organization\u002Frouter-tags-and-openapi-grouping\u002Findex",[549],{"title":545,"path":546,"stem":547},{"title":551,"path":552,"stem":553,"children":554},"Versioning APIs with FastAPI Routers","\u002Fcore-architecture-routing-patterns\u002Fmodular-router-organization\u002Fversioning-apis-with-routers","core-architecture-routing-patterns\u002Fmodular-router-organization\u002Fversioning-apis-with-routers\u002Findex",[555],{"title":551,"path":552,"stem":553},{"title":557,"path":558,"stem":559,"children":560},"The FastAPI Request\u002FResponse Lifecycle","\u002Fcore-architecture-routing-patterns\u002Frequest-response-lifecycle","core-architecture-routing-patterns\u002Frequest-response-lifecycle\u002Findex",[561,562,568,574],{"title":557,"path":558,"stem":559},{"title":563,"path":564,"stem":565,"children":566},"How a Request Flows Through FastAPI","\u002Fcore-architecture-routing-patterns\u002Frequest-response-lifecycle\u002Fhow-a-request-flows-through-fastapi","core-architecture-routing-patterns\u002Frequest-response-lifecycle\u002Fhow-a-request-flows-through-fastapi\u002Findex",[567],{"title":563,"path":564,"stem":565},{"title":569,"path":570,"stem":571,"children":572},"Response Model and Serialization Order","\u002Fcore-architecture-routing-patterns\u002Frequest-response-lifecycle\u002Fresponse-model-and-serialization-order","core-architecture-routing-patterns\u002Frequest-response-lifecycle\u002Fresponse-model-and-serialization-order\u002Findex",[573],{"title":569,"path":570,"stem":571},{"title":575,"path":576,"stem":577,"children":578},"Streaming and File Responses in FastAPI","\u002Fcore-architecture-routing-patterns\u002Frequest-response-lifecycle\u002Fstreaming-and-file-responses","core-architecture-routing-patterns\u002Frequest-response-lifecycle\u002Fstreaming-and-file-responses\u002Findex",[579],{"title":575,"path":576,"stem":577},{"id":581,"title":61,"body":582,"dateModified":2054,"datePublished":2054,"description":2055,"extension":2056,"faq":2057,"howto":2068,"meta":2069,"navigation":876,"path":62,"seo":2082,"stem":63,"type":2083,"__hash__":2084},"content\u002Fadvanced-pydantic-validation-serialization\u002Fjson-schema-customization\u002Fexamples-in-openapi-schema\u002Findex.md",{"type":583,"value":584,"toc":2043},"minimark",[585,589,596,625,634,639,666,669,767,771,774,787,795,816,827,830,834,837,1239,1242,1554,1557,1564,1582,1585,1591,1596,1602,1608,1628,1639,1643,1646,1808,1811,1814,1895,1899,1905,1911,1922,1942,1955,1959,1970,1979,1985,1991,2000,2004,2039],[586,587,61],"h1",{"id":588},"examples-in-the-openapi-schema-with-fastapi",[590,591,592],"p",{},[593,594,595],"strong",{},"Key takeaways:",[597,598,599,607,613,619,622],"ul",{},[600,601,602,606],"li",{},[603,604,605],"code",{},"Field(examples=[...])"," documents one property and travels with the model everywhere.",[600,608,609,612],{},[603,610,611],{},"json_schema_extra"," on the model config carries a whole sample payload.",[600,614,615,618],{},[603,616,617],{},"Body(openapi_examples={...})"," gives one operation a named, described set of examples.",[600,620,621],{},"Route-level examples win the request-body dropdown; the model example still renders elsewhere.",[600,623,624],{},"Examples are never validated against the model, so a stale one produces confidently wrong docs.",[590,626,627,628,633],{},"This guide extends ",[629,630,632],"a",{"href":631},"\u002Fadvanced-pydantic-validation-serialization\u002Fjson-schema-customization\u002F","JSON Schema Customization",", which covers shaping the generated schema; this page is about the part of that schema a human actually reads first.",[635,636,638],"h2",{"id":637},"the-problem-this-solves","The Problem This Solves",[590,640,641,642,645,646,649,650,653,654,657,658,661,662,665],{},"A consumer opens your ",[603,643,644],{},"\u002Fdocs"," page and sees a request body sample of ",[603,647,648],{},"{\"customer_email\": \"string\", \"currency\": \"string\", \"items\": []}",". It is technically accurate and completely useless. They cannot tell whether ",[603,651,652],{},"currency"," wants ",[603,655,656],{},"GBP"," or ",[603,659,660],{},"British Pound",", whether ",[603,663,664],{},"items"," may be empty, or what an SKU looks like. So they guess, get a 422, and open a support ticket — or worse, copy the placeholder into an integration test and ship it.",[590,667,668],{},"Three different mechanisms in FastAPI fix this, they surface in different places, and the one people reach for first is usually not the one they wanted.",[670,671,677,681,685,692,696,707,712,719,723,726,729,732,736,739,742,744,747,751,756,759,762,764],"svg",{"viewBox":672,"role":673,"ariaLabel":674,"xmlns":675,"style":676},"0 0 720 290","img","Three ways to declare examples and where each renders in the docs","http:\u002F\u002Fwww.w3.org\u002F2000\u002Fsvg","width:100%;height:auto;max-width:720px;margin:2rem 0",[678,679,680],"title",{},"Three example mechanisms and where each surfaces",[682,683,684],"desc",{},"Field examples render as per-property hints in the schema, a model-level json_schema_extra example renders as the whole-body sample, and route-level openapi_examples fill the named Examples dropdown in Swagger UI.",[686,687,691],"text",{"x":688,"y":689,"style":690},"170","30","text-anchor:middle;fill:#00796B;font:700 13px sans-serif","declared on",[686,693,695],{"x":694,"y":689,"style":690},"550","renders as",[697,698],"rect",{"x":699,"y":700,"width":701,"height":702,"rx":703,"fill":704,"stroke":705,"strokeWidth":706},"20","48","300","56","8","none","currentColor","1.5",[686,708,711],{"x":688,"y":709,"style":710},"82","text-anchor:middle;fill:currentColor;font:400 12px sans-serif","Field(examples=[...]) — one property",[713,714],"line",{"x1":715,"y1":716,"x2":717,"y2":716,"stroke":718,"strokeWidth":706},"320","76","392","#00796B",[720,721],"polygon",{"points":722,"fill":718},"392,71 402,76 392,81",[697,724],{"x":725,"y":700,"width":701,"height":702,"rx":703,"fill":704,"stroke":705,"strokeWidth":706},"400",[686,727,728],{"x":694,"y":709,"style":710},"per-field hint, wherever reused",[697,730],{"x":699,"y":731,"width":701,"height":702,"rx":703,"fill":704,"stroke":705,"strokeWidth":706},"124",[686,733,735],{"x":688,"y":734,"style":710},"158","json_schema_extra — whole model",[713,737],{"x1":715,"y1":738,"x2":717,"y2":738,"stroke":718,"strokeWidth":706},"152",[720,740],{"points":741,"fill":718},"392,147 402,152 392,157",[697,743],{"x":725,"y":731,"width":701,"height":702,"rx":703,"fill":704,"stroke":705,"strokeWidth":706},[686,745,746],{"x":694,"y":734,"style":710},"whole-body sample, incl. responses",[697,748],{"x":699,"y":749,"width":701,"height":702,"rx":703,"fill":704,"stroke":718,"strokeWidth":750},"200","2",[686,752,755],{"x":688,"y":753,"style":754},"234","text-anchor:middle;fill:#00796B;font:400 12px sans-serif","Body(openapi_examples) — one route",[713,757],{"x1":715,"y1":758,"x2":717,"y2":758,"stroke":718,"strokeWidth":706},"228",[720,760],{"points":761,"fill":718},"392,223 402,228 392,233",[697,763],{"x":725,"y":749,"width":701,"height":702,"rx":703,"fill":704,"stroke":718,"strokeWidth":750},[686,765,766],{"x":694,"y":753,"style":754},"named Examples dropdown",[635,768,770],{"id":769},"why-it-happens","Why It Happens",[590,772,773],{},"The three mechanisms live at different levels of the OpenAPI document, and that is the entire explanation for their different behaviour.",[590,775,776,778,779,782,783,786],{},[603,777,605],{}," is Pydantic's. It writes an ",[603,780,781],{},"examples"," array into the property's own schema object, inside ",[603,784,785],{},"components.schemas.\u003CModel>.properties.\u003Cfield>",". Because it lives on the model, it appears everywhere that model is referenced — request bodies, response bodies, nested inside other models — and it survives being reused across a dozen endpoints.",[590,788,789,791,792,794],{},[603,790,611],{}," is also Pydantic's, one level up. Whatever dictionary you supply is merged into the model's schema object verbatim. Putting an ",[603,793,781],{}," key there attaches a full sample payload to the model itself. It is the escape hatch for anything JSON Schema supports that Pydantic has no dedicated argument for.",[590,796,797,799,800,803,804,807,808,811,812,815],{},[603,798,617],{}," is FastAPI's, and it lives outside the schema entirely. It writes into ",[603,801,802],{},"paths.\u003Cpath>.\u003Cmethod>.requestBody.content[\"application\u002Fjson\"].examples"," — the OpenAPI media-type object, not the JSON Schema. That location is why it supports things JSON Schema cannot express: each entry carries a ",[603,805,806],{},"summary"," and a ",[603,809,810],{},"description"," alongside its ",[603,813,814],{},"value",", which is what Swagger UI renders as a labelled dropdown.",[590,817,818,819,822,823,826],{},"Because the media-type object is more specific than the schema it references, a route-level ",[603,820,821],{},"openapi_examples"," mapping wins the request-body display for that operation. The model-level example is not discarded — it is still in ",[603,824,825],{},"components"," and still renders where the model is shown for other purposes, including the response sample.",[590,828,829],{},"None of the three is ever validated. Pydantic treats an example as opaque metadata and copies it into the schema without checking it against the field it decorates. That is a deliberate design choice — examples sometimes need to be deliberately invalid — and it is the reason examples rot.",[635,831,833],{"id":832},"the-fix","The Fix",[590,835,836],{},"Use all three, at the level each is good at. Field examples for values whose format is not obvious, a model example for the canonical payload, and route examples where a specific operation benefits from several named cases.",[838,839,844],"pre",{"className":840,"code":841,"language":842,"meta":843,"style":843},"language-python shiki shiki-themes github-light-high-contrast","\"\"\"Attach examples at field, model and route level and read them back out of the OpenAPI document.\"\"\"\nfrom typing import Annotated\n\nfrom fastapi import Body, FastAPI\nfrom pydantic import BaseModel, ConfigDict, Field\n\n\nclass LineItem(BaseModel):\n    sku: Annotated[str, Field(examples=[\"SKU-4417\"], description=\"Catalogue identifier.\")]\n    quantity: Annotated[int, Field(gt=0, examples=[2], description=\"Units ordered.\")]\n\n\nclass CreateOrder(BaseModel):\n    \"\"\"A model-level example is the whole payload, ready to copy out of Swagger UI.\"\"\"\n\n    model_config = ConfigDict(\n        json_schema_extra={\n            \"examples\": [\n                {\n                    \"customer_email\": \"ada@example.com\",\n                    \"currency\": \"GBP\",\n                    \"items\": [{\"sku\": \"SKU-4417\", \"quantity\": 2}],\n                }\n            ]\n        }\n    )\n\n    customer_email: Annotated[str, Field(examples=[\"ada@example.com\"])]\n    currency: Annotated[str, Field(min_length=3, max_length=3, examples=[\"GBP\", \"USD\"])]\n    items: list[LineItem]\n","python","",[603,845,846,854,871,878,891,904,909,914,934,970,1011,1016,1021,1035,1041,1046,1057,1068,1077,1083,1098,1111,1139,1145,1151,1157,1163,1168,1189,1233],{"__ignoreMap":843},[847,848,850],"span",{"class":713,"line":849},1,[847,851,853],{"class":852},"sYEJz","\"\"\"Attach examples at field, model and route level and read them back out of the OpenAPI document.\"\"\"\n",[847,855,857,861,865,868],{"class":713,"line":856},2,[847,858,860],{"class":859},"sTJeM","from",[847,862,864],{"class":863},"sigWx"," typing ",[847,866,867],{"class":859},"import",[847,869,870],{"class":863}," Annotated\n",[847,872,874],{"class":713,"line":873},3,[847,875,877],{"emptyLinePlaceholder":876},true,"\n",[847,879,881,883,886,888],{"class":713,"line":880},4,[847,882,860],{"class":859},[847,884,885],{"class":863}," fastapi ",[847,887,867],{"class":859},[847,889,890],{"class":863}," Body, FastAPI\n",[847,892,894,896,899,901],{"class":713,"line":893},5,[847,895,860],{"class":859},[847,897,898],{"class":863}," pydantic ",[847,900,867],{"class":859},[847,902,903],{"class":863}," BaseModel, ConfigDict, Field\n",[847,905,907],{"class":713,"line":906},6,[847,908,877],{"emptyLinePlaceholder":876},[847,910,912],{"class":713,"line":911},7,[847,913,877],{"emptyLinePlaceholder":876},[847,915,917,920,924,927,931],{"class":713,"line":916},8,[847,918,919],{"class":859},"class",[847,921,923],{"class":922},"sV4o_"," LineItem",[847,925,926],{"class":863},"(",[847,928,930],{"class":929},"sacAq","BaseModel",[847,932,933],{"class":863},"):\n",[847,935,937,940,943,946,948,951,954,957,960,962,964,967],{"class":713,"line":936},9,[847,938,939],{"class":863},"    sku: Annotated[",[847,941,942],{"class":929},"str",[847,944,945],{"class":863},", Field(",[847,947,781],{"class":922},[847,949,950],{"class":859},"=",[847,952,953],{"class":863},"[",[847,955,956],{"class":852},"\"SKU-4417\"",[847,958,959],{"class":863},"], ",[847,961,810],{"class":922},[847,963,950],{"class":859},[847,965,966],{"class":852},"\"Catalogue identifier.\"",[847,968,969],{"class":863},")]\n",[847,971,973,976,979,981,984,986,989,992,994,996,998,1000,1002,1004,1006,1009],{"class":713,"line":972},10,[847,974,975],{"class":863},"    quantity: Annotated[",[847,977,978],{"class":929},"int",[847,980,945],{"class":863},[847,982,983],{"class":922},"gt",[847,985,950],{"class":859},[847,987,988],{"class":929},"0",[847,990,991],{"class":863},", ",[847,993,781],{"class":922},[847,995,950],{"class":859},[847,997,953],{"class":863},[847,999,750],{"class":929},[847,1001,959],{"class":863},[847,1003,810],{"class":922},[847,1005,950],{"class":859},[847,1007,1008],{"class":852},"\"Units ordered.\"",[847,1010,969],{"class":863},[847,1012,1014],{"class":713,"line":1013},11,[847,1015,877],{"emptyLinePlaceholder":876},[847,1017,1019],{"class":713,"line":1018},12,[847,1020,877],{"emptyLinePlaceholder":876},[847,1022,1024,1026,1029,1031,1033],{"class":713,"line":1023},13,[847,1025,919],{"class":859},[847,1027,1028],{"class":922}," CreateOrder",[847,1030,926],{"class":863},[847,1032,930],{"class":929},[847,1034,933],{"class":863},[847,1036,1038],{"class":713,"line":1037},14,[847,1039,1040],{"class":852},"    \"\"\"A model-level example is the whole payload, ready to copy out of Swagger UI.\"\"\"\n",[847,1042,1044],{"class":713,"line":1043},15,[847,1045,877],{"emptyLinePlaceholder":876},[847,1047,1049,1052,1054],{"class":713,"line":1048},16,[847,1050,1051],{"class":863},"    model_config ",[847,1053,950],{"class":859},[847,1055,1056],{"class":863}," ConfigDict(\n",[847,1058,1060,1063,1065],{"class":713,"line":1059},17,[847,1061,1062],{"class":922},"        json_schema_extra",[847,1064,950],{"class":859},[847,1066,1067],{"class":863},"{\n",[847,1069,1071,1074],{"class":713,"line":1070},18,[847,1072,1073],{"class":852},"            \"examples\"",[847,1075,1076],{"class":863},": [\n",[847,1078,1080],{"class":713,"line":1079},19,[847,1081,1082],{"class":863},"                {\n",[847,1084,1086,1089,1092,1095],{"class":713,"line":1085},20,[847,1087,1088],{"class":852},"                    \"customer_email\"",[847,1090,1091],{"class":863},": ",[847,1093,1094],{"class":852},"\"ada@example.com\"",[847,1096,1097],{"class":863},",\n",[847,1099,1101,1104,1106,1109],{"class":713,"line":1100},21,[847,1102,1103],{"class":852},"                    \"currency\"",[847,1105,1091],{"class":863},[847,1107,1108],{"class":852},"\"GBP\"",[847,1110,1097],{"class":863},[847,1112,1114,1117,1120,1123,1125,1127,1129,1132,1134,1136],{"class":713,"line":1113},22,[847,1115,1116],{"class":852},"                    \"items\"",[847,1118,1119],{"class":863},": [{",[847,1121,1122],{"class":852},"\"sku\"",[847,1124,1091],{"class":863},[847,1126,956],{"class":852},[847,1128,991],{"class":863},[847,1130,1131],{"class":852},"\"quantity\"",[847,1133,1091],{"class":863},[847,1135,750],{"class":929},[847,1137,1138],{"class":863},"}],\n",[847,1140,1142],{"class":713,"line":1141},23,[847,1143,1144],{"class":863},"                }\n",[847,1146,1148],{"class":713,"line":1147},24,[847,1149,1150],{"class":863},"            ]\n",[847,1152,1154],{"class":713,"line":1153},25,[847,1155,1156],{"class":863},"        }\n",[847,1158,1160],{"class":713,"line":1159},26,[847,1161,1162],{"class":863},"    )\n",[847,1164,1166],{"class":713,"line":1165},27,[847,1167,877],{"emptyLinePlaceholder":876},[847,1169,1171,1174,1176,1178,1180,1182,1184,1186],{"class":713,"line":1170},28,[847,1172,1173],{"class":863},"    customer_email: Annotated[",[847,1175,942],{"class":929},[847,1177,945],{"class":863},[847,1179,781],{"class":922},[847,1181,950],{"class":859},[847,1183,953],{"class":863},[847,1185,1094],{"class":852},[847,1187,1188],{"class":863},"])]\n",[847,1190,1192,1195,1197,1199,1202,1204,1207,1209,1212,1214,1216,1218,1220,1222,1224,1226,1228,1231],{"class":713,"line":1191},29,[847,1193,1194],{"class":863},"    currency: Annotated[",[847,1196,942],{"class":929},[847,1198,945],{"class":863},[847,1200,1201],{"class":922},"min_length",[847,1203,950],{"class":859},[847,1205,1206],{"class":929},"3",[847,1208,991],{"class":863},[847,1210,1211],{"class":922},"max_length",[847,1213,950],{"class":859},[847,1215,1206],{"class":929},[847,1217,991],{"class":863},[847,1219,781],{"class":922},[847,1221,950],{"class":859},[847,1223,953],{"class":863},[847,1225,1108],{"class":852},[847,1227,991],{"class":863},[847,1229,1230],{"class":852},"\"USD\"",[847,1232,1188],{"class":863},[847,1234,1236],{"class":713,"line":1235},30,[847,1237,1238],{"class":863},"    items: list[LineItem]\n",[590,1240,1241],{},"The route adds two named cases, one of which is deliberately invalid so a reader can watch the 422 happen from inside the docs page:",[838,1243,1245],{"className":840,"code":1244,"language":842,"meta":843,"style":843},"@app.post(\"\u002Forders\", response_model=Order, operation_id=\"createOrder\", tags=[\"orders\"])\nasync def create_order(\n    order: Annotated[\n        CreateOrder,\n        Body(\n            openapi_examples={\n                \"single_item\": {\n                    \"summary\": \"One line item\",\n                    \"description\": \"The common case.\",\n                    \"value\": {\n                        \"customer_email\": \"ada@example.com\",\n                        \"currency\": \"GBP\",\n                        \"items\": [{\"sku\": \"SKU-4417\", \"quantity\": 1}],\n                    },\n                },\n                \"rejected\": {\n                    \"summary\": \"Invalid — currency too long\",\n                    \"description\": \"Swagger UI will submit this and show you the 422.\",\n                    \"value\": {\n                        \"customer_email\": \"ada@example.com\",\n                        \"currency\": \"POUNDS\",\n                        \"items\": [{\"sku\": \"SKU-4417\", \"quantity\": 1}],\n                    },\n                },\n            }\n        ),\n    ],\n) -> Order:\n    return Order(id=9001, **order.model_dump())\n",[603,1246,1247,1291,1305,1310,1315,1320,1329,1337,1349,1361,1368,1379,1390,1414,1419,1424,1431,1442,1453,1459,1469,1480,1502,1506,1510,1515,1520,1525,1530],{"__ignoreMap":843},[847,1248,1249,1253,1255,1258,1260,1263,1265,1268,1271,1273,1276,1278,1281,1283,1285,1288],{"class":713,"line":849},[847,1250,1252],{"class":1251},"s3dhs","@app.post",[847,1254,926],{"class":863},[847,1256,1257],{"class":852},"\"\u002Forders\"",[847,1259,991],{"class":863},[847,1261,1262],{"class":922},"response_model",[847,1264,950],{"class":859},[847,1266,1267],{"class":863},"Order, ",[847,1269,1270],{"class":922},"operation_id",[847,1272,950],{"class":859},[847,1274,1275],{"class":852},"\"createOrder\"",[847,1277,991],{"class":863},[847,1279,1280],{"class":922},"tags",[847,1282,950],{"class":859},[847,1284,953],{"class":863},[847,1286,1287],{"class":852},"\"orders\"",[847,1289,1290],{"class":863},"])\n",[847,1292,1293,1296,1299,1302],{"class":713,"line":856},[847,1294,1295],{"class":859},"async",[847,1297,1298],{"class":859}," def",[847,1300,1301],{"class":1251}," create_order",[847,1303,1304],{"class":863},"(\n",[847,1306,1307],{"class":713,"line":873},[847,1308,1309],{"class":863},"    order: Annotated[\n",[847,1311,1312],{"class":713,"line":880},[847,1313,1314],{"class":863},"        CreateOrder,\n",[847,1316,1317],{"class":713,"line":893},[847,1318,1319],{"class":863},"        Body(\n",[847,1321,1322,1325,1327],{"class":713,"line":906},[847,1323,1324],{"class":922},"            openapi_examples",[847,1326,950],{"class":859},[847,1328,1067],{"class":863},[847,1330,1331,1334],{"class":713,"line":911},[847,1332,1333],{"class":852},"                \"single_item\"",[847,1335,1336],{"class":863},": {\n",[847,1338,1339,1342,1344,1347],{"class":713,"line":916},[847,1340,1341],{"class":852},"                    \"summary\"",[847,1343,1091],{"class":863},[847,1345,1346],{"class":852},"\"One line item\"",[847,1348,1097],{"class":863},[847,1350,1351,1354,1356,1359],{"class":713,"line":936},[847,1352,1353],{"class":852},"                    \"description\"",[847,1355,1091],{"class":863},[847,1357,1358],{"class":852},"\"The common case.\"",[847,1360,1097],{"class":863},[847,1362,1363,1366],{"class":713,"line":972},[847,1364,1365],{"class":852},"                    \"value\"",[847,1367,1336],{"class":863},[847,1369,1370,1373,1375,1377],{"class":713,"line":1013},[847,1371,1372],{"class":852},"                        \"customer_email\"",[847,1374,1091],{"class":863},[847,1376,1094],{"class":852},[847,1378,1097],{"class":863},[847,1380,1381,1384,1386,1388],{"class":713,"line":1018},[847,1382,1383],{"class":852},"                        \"currency\"",[847,1385,1091],{"class":863},[847,1387,1108],{"class":852},[847,1389,1097],{"class":863},[847,1391,1392,1395,1397,1399,1401,1403,1405,1407,1409,1412],{"class":713,"line":1023},[847,1393,1394],{"class":852},"                        \"items\"",[847,1396,1119],{"class":863},[847,1398,1122],{"class":852},[847,1400,1091],{"class":863},[847,1402,956],{"class":852},[847,1404,991],{"class":863},[847,1406,1131],{"class":852},[847,1408,1091],{"class":863},[847,1410,1411],{"class":929},"1",[847,1413,1138],{"class":863},[847,1415,1416],{"class":713,"line":1037},[847,1417,1418],{"class":863},"                    },\n",[847,1420,1421],{"class":713,"line":1043},[847,1422,1423],{"class":863},"                },\n",[847,1425,1426,1429],{"class":713,"line":1048},[847,1427,1428],{"class":852},"                \"rejected\"",[847,1430,1336],{"class":863},[847,1432,1433,1435,1437,1440],{"class":713,"line":1059},[847,1434,1341],{"class":852},[847,1436,1091],{"class":863},[847,1438,1439],{"class":852},"\"Invalid — currency too long\"",[847,1441,1097],{"class":863},[847,1443,1444,1446,1448,1451],{"class":713,"line":1070},[847,1445,1353],{"class":852},[847,1447,1091],{"class":863},[847,1449,1450],{"class":852},"\"Swagger UI will submit this and show you the 422.\"",[847,1452,1097],{"class":863},[847,1454,1455,1457],{"class":713,"line":1079},[847,1456,1365],{"class":852},[847,1458,1336],{"class":863},[847,1460,1461,1463,1465,1467],{"class":713,"line":1085},[847,1462,1372],{"class":852},[847,1464,1091],{"class":863},[847,1466,1094],{"class":852},[847,1468,1097],{"class":863},[847,1470,1471,1473,1475,1478],{"class":713,"line":1100},[847,1472,1383],{"class":852},[847,1474,1091],{"class":863},[847,1476,1477],{"class":852},"\"POUNDS\"",[847,1479,1097],{"class":863},[847,1481,1482,1484,1486,1488,1490,1492,1494,1496,1498,1500],{"class":713,"line":1113},[847,1483,1394],{"class":852},[847,1485,1119],{"class":863},[847,1487,1122],{"class":852},[847,1489,1091],{"class":863},[847,1491,956],{"class":852},[847,1493,991],{"class":863},[847,1495,1131],{"class":852},[847,1497,1091],{"class":863},[847,1499,1411],{"class":929},[847,1501,1138],{"class":863},[847,1503,1504],{"class":713,"line":1141},[847,1505,1418],{"class":863},[847,1507,1508],{"class":713,"line":1147},[847,1509,1423],{"class":863},[847,1511,1512],{"class":713,"line":1153},[847,1513,1514],{"class":863},"            }\n",[847,1516,1517],{"class":713,"line":1159},[847,1518,1519],{"class":863},"        ),\n",[847,1521,1522],{"class":713,"line":1165},[847,1523,1524],{"class":863},"    ],\n",[847,1526,1527],{"class":713,"line":1170},[847,1528,1529],{"class":863},") -> Order:\n",[847,1531,1532,1535,1538,1541,1543,1546,1548,1551],{"class":713,"line":1191},[847,1533,1534],{"class":859},"    return",[847,1536,1537],{"class":863}," Order(",[847,1539,1540],{"class":922},"id",[847,1542,950],{"class":859},[847,1544,1545],{"class":929},"9001",[847,1547,991],{"class":863},[847,1549,1550],{"class":859},"**",[847,1552,1553],{"class":863},"order.model_dump())\n",[590,1555,1556],{},"Reading all three back out of the generated document, from a real run of this app:",[838,1558,1562],{"className":1559,"code":1561,"language":686,"meta":843},[1560],"language-text","$ GET \u002F_meta\u002Fexamples\n200 OK\n{\n  \"route_level_openapi_examples\": [\n    \"rejected\",\n    \"single_item\"\n  ],\n  \"model_level_example\": [\n    {\n      \"currency\": \"GBP\",\n      \"customer_email\": \"ada@example.com\",\n      \"items\": [\n        {\n          \"quantity\": 2,\n          \"sku\": \"SKU-4417\"\n        }\n      ]\n    }\n  ],\n  \"field_level_examples\": {\n    \"customer_email\": [\n      \"ada@example.com\"\n    ],\n    \"currency\": [\n      \"GBP\",\n      \"USD\"\n    ],\n    \"items\": null\n  },\n  \"nested_field_examples\": {\n    \"sku\": [\n      \"SKU-4417\"\n    ],\n    \"quantity\": [\n      2\n    ]\n  }\n}\n",[603,1563,1561],{"__ignoreMap":843},[590,1565,1566,1567,1570,1571,1573,1574,1577,1578,1581],{},"Every layer landed where the previous section said it would. The route examples are in the media-type object under their names. The model example sits on ",[603,1568,1569],{},"CreateOrder"," itself. The field examples are on the properties, and ",[603,1572,664],{}," is ",[603,1575,1576],{},"null"," because no example was declared for it — the nested ",[603,1579,1580],{},"LineItem"," supplies its own instead, which is the reuse benefit of putting examples on models rather than on endpoints.",[590,1583,1584],{},"And the deliberately invalid example does produce the 422 it promises:",[838,1586,1589],{"className":1587,"code":1588,"language":686,"meta":843},[1560],"$ POST \u002Forders  {\"customer_email\": \"ada@example.com\", \"currency\": \"POUNDS\", \"items\": [{\"sku\": \"SKU-4417\", \"quantity\": 1}]}\n422 Unprocessable Entity\n{\n  \"detail\": [\n    {\n      \"type\": \"string_too_long\",\n      \"loc\": [\n        \"body\",\n        \"currency\"\n      ],\n      \"msg\": \"String should have at most 3 characters\",\n      \"input\": \"POUNDS\",\n      \"ctx\": {\n        \"max_length\": 3\n      }\n    }\n  ]\n}\n",[603,1590,1588],{"__ignoreMap":843},[1592,1593,1595],"h3",{"id":1594},"what-this-actually-looks-like","What this actually looks like",[590,1597,1598,1599,1601],{},"This is the real ",[603,1600,644],{}," page for the app above, photographed from a running instance with the operation expanded:",[590,1603,1604],{},[673,1605],{"alt":1606,"src":1607},"Swagger UI for the Orders API with the POST \u002Forders operation expanded, showing an Examples dropdown set to One line item, the example JSON body with customer_email ada@example.com and currency GBP, the example description The common case, and the 200 response sample carrying the model-level example","\u002Fimg\u002Fschema-openapi-examples-docs.png",[590,1609,1610,1611,1614,1615,1617,1618,1620,1621,1623,1624,1627],{},"The layering is visible in one screen. The ",[593,1612,1613],{},"Examples"," dropdown above the request body is the route-level ",[603,1616,821],{},", labelled with the ",[603,1619,806],{}," you wrote and captioned underneath with the ",[603,1622,810],{}," — the second entry, \"Invalid — currency too long\", is one selection away and submits through ",[593,1625,1626],{},"Try it out"," to produce the 422 above.",[590,1629,1630,1631,1634,1635,1638],{},"Below, the 200 response's ",[593,1632,1633],{},"Example Value"," shows ",[603,1636,1637],{},"\"quantity\": 2"," and the model-level payload, because responses have no route-level examples to override them. That is the precedence rule made concrete: the route examples took the request body, the model example kept everything else.",[635,1640,1642],{"id":1641},"verification","Verification",[590,1644,1645],{},"Examples are not validated, so validate them yourself. This is a five-line test that keeps every published example honest:",[838,1647,1649],{"className":840,"code":1648,"language":842,"meta":843,"style":843},"def test_every_openapi_example_is_valid():\n    spec = app.openapi()\n    body = spec[\"paths\"][\"\u002Forders\"][\"post\"][\"requestBody\"][\"content\"][\"application\u002Fjson\"]\n    for name, example in body[\"examples\"].items():\n        if name == \"rejected\":\n            continue                      # deliberately invalid, documented as such\n        CreateOrder.model_validate(example[\"value\"])\n\n\ndef test_model_example_is_valid():\n    for example in CreateOrder.model_json_schema()[\"examples\"]:\n        CreateOrder.model_validate(example)\n",[603,1650,1651,1662,1672,1713,1733,1750,1759,1769,1773,1777,1786,1803],{"__ignoreMap":843},[847,1652,1653,1656,1659],{"class":713,"line":849},[847,1654,1655],{"class":859},"def",[847,1657,1658],{"class":1251}," test_every_openapi_example_is_valid",[847,1660,1661],{"class":863},"():\n",[847,1663,1664,1667,1669],{"class":713,"line":856},[847,1665,1666],{"class":863},"    spec ",[847,1668,950],{"class":859},[847,1670,1671],{"class":863}," app.openapi()\n",[847,1673,1674,1677,1679,1682,1685,1688,1690,1692,1695,1697,1700,1702,1705,1707,1710],{"class":713,"line":873},[847,1675,1676],{"class":863},"    body ",[847,1678,950],{"class":859},[847,1680,1681],{"class":863}," spec[",[847,1683,1684],{"class":852},"\"paths\"",[847,1686,1687],{"class":863},"][",[847,1689,1257],{"class":852},[847,1691,1687],{"class":863},[847,1693,1694],{"class":852},"\"post\"",[847,1696,1687],{"class":863},[847,1698,1699],{"class":852},"\"requestBody\"",[847,1701,1687],{"class":863},[847,1703,1704],{"class":852},"\"content\"",[847,1706,1687],{"class":863},[847,1708,1709],{"class":852},"\"application\u002Fjson\"",[847,1711,1712],{"class":863},"]\n",[847,1714,1715,1718,1721,1724,1727,1730],{"class":713,"line":880},[847,1716,1717],{"class":859},"    for",[847,1719,1720],{"class":863}," name, example ",[847,1722,1723],{"class":859},"in",[847,1725,1726],{"class":863}," body[",[847,1728,1729],{"class":852},"\"examples\"",[847,1731,1732],{"class":863},"].items():\n",[847,1734,1735,1738,1741,1744,1747],{"class":713,"line":893},[847,1736,1737],{"class":859},"        if",[847,1739,1740],{"class":863}," name ",[847,1742,1743],{"class":859},"==",[847,1745,1746],{"class":852}," \"rejected\"",[847,1748,1749],{"class":863},":\n",[847,1751,1752,1755],{"class":713,"line":906},[847,1753,1754],{"class":859},"            continue",[847,1756,1758],{"class":1757},"sFeEa","                      # deliberately invalid, documented as such\n",[847,1760,1761,1764,1767],{"class":713,"line":911},[847,1762,1763],{"class":863},"        CreateOrder.model_validate(example[",[847,1765,1766],{"class":852},"\"value\"",[847,1768,1290],{"class":863},[847,1770,1771],{"class":713,"line":916},[847,1772,877],{"emptyLinePlaceholder":876},[847,1774,1775],{"class":713,"line":936},[847,1776,877],{"emptyLinePlaceholder":876},[847,1778,1779,1781,1784],{"class":713,"line":972},[847,1780,1655],{"class":859},[847,1782,1783],{"class":1251}," test_model_example_is_valid",[847,1785,1661],{"class":863},[847,1787,1788,1790,1793,1795,1798,1800],{"class":713,"line":1013},[847,1789,1717],{"class":859},[847,1791,1792],{"class":863}," example ",[847,1794,1723],{"class":859},[847,1796,1797],{"class":863}," CreateOrder.model_json_schema()[",[847,1799,1729],{"class":852},[847,1801,1802],{"class":863},"]:\n",[847,1804,1805],{"class":713,"line":1018},[847,1806,1807],{"class":863},"        CreateOrder.model_validate(example)\n",[590,1809,1810],{},"Run it in CI and a field rename that leaves the examples behind fails the build instead of shipping. This is the single highest-value test on this page, because the failure mode it catches — documentation that is wrong with total confidence — is otherwise only discovered by a frustrated consumer.",[590,1812,1813],{},"It is also worth asserting that fields consumers commonly get wrong have examples at all:",[838,1815,1817],{"className":840,"code":1816,"language":842,"meta":843,"style":843},"def test_ambiguous_fields_are_exemplified():\n    props = CreateOrder.model_json_schema()[\"properties\"]\n    for field in (\"currency\", \"customer_email\"):\n        assert props[field].get(\"examples\"), f\"{field} ships with no example\"\n",[603,1818,1819,1828,1842,1864],{"__ignoreMap":843},[847,1820,1821,1823,1826],{"class":713,"line":849},[847,1822,1655],{"class":859},[847,1824,1825],{"class":1251}," test_ambiguous_fields_are_exemplified",[847,1827,1661],{"class":863},[847,1829,1830,1833,1835,1837,1840],{"class":713,"line":856},[847,1831,1832],{"class":863},"    props ",[847,1834,950],{"class":859},[847,1836,1797],{"class":863},[847,1838,1839],{"class":852},"\"properties\"",[847,1841,1712],{"class":863},[847,1843,1844,1846,1849,1851,1854,1857,1859,1862],{"class":713,"line":873},[847,1845,1717],{"class":859},[847,1847,1848],{"class":863}," field ",[847,1850,1723],{"class":859},[847,1852,1853],{"class":863}," (",[847,1855,1856],{"class":852},"\"currency\"",[847,1858,991],{"class":863},[847,1860,1861],{"class":852},"\"customer_email\"",[847,1863,933],{"class":863},[847,1865,1866,1869,1872,1874,1877,1880,1883,1886,1889,1892],{"class":713,"line":880},[847,1867,1868],{"class":859},"        assert",[847,1870,1871],{"class":863}," props[field].get(",[847,1873,1729],{"class":852},[847,1875,1876],{"class":863},"), ",[847,1878,1879],{"class":859},"f",[847,1881,1882],{"class":852},"\"",[847,1884,1885],{"class":859},"{",[847,1887,1888],{"class":863},"field",[847,1890,1891],{"class":859},"}",[847,1893,1894],{"class":852}," ships with no example\"\n",[635,1896,1898],{"id":1897},"trade-offs-and-when-not-to","Trade-offs and When Not To",[590,1900,1901,1904],{},[593,1902,1903],{},"Examples are duplication, and duplication drifts."," Every example is a copy of a payload shape that also exists in the model. The CI test above is what makes that duplication safe; without it, examples are a liability that grows with the API.",[590,1906,1907,1910],{},[593,1908,1909],{},"Do not put real data in examples."," They are public, they end up in generated SDK docstrings and in search results. Real customer emails, real account ids and anything resembling a live token do not belong there.",[590,1912,1913,1916,1917,1921],{},[593,1914,1915],{},"Route-level examples do not scale across an API."," They live on one operation and cannot be reused, so an API with forty endpoints each carrying three named examples becomes a maintenance problem. Reach for them where the multi-case story genuinely helps — a polymorphic body, a deliberately-failing case, a rarely-used optional shape — and rely on model examples everywhere else. Discriminated bodies in particular deserve one named example per variant, as ",[629,1918,1920],{"href":1919},"\u002Fadvanced-pydantic-validation-serialization\u002Fjson-schema-customization\u002Fdiscriminated-unions-in-openapi\u002F","Discriminated Unions in OpenAPI"," shows.",[590,1923,1924,1931,1932,1934,1935,1937,1938,1941],{},[593,1925,1926,1927,1930],{},"The older ",[603,1928,1929],{},"example"," singular is deprecated."," OpenAPI 3.1 and JSON Schema use the plural ",[603,1933,781],{}," array. FastAPI still accepts a singular ",[603,1936,1929],{}," argument for compatibility, but new code should use ",[603,1939,1940],{},"examples=[...]"," — the plural is what modern tooling reads.",[590,1943,1944,1947,1948,1951,1952,1954],{},[593,1945,1946],{},"Examples do not replace descriptions."," An example shows the shape; it does not explain the semantics. ",[603,1949,1950],{},"\"idempotency_key\": \"req-abc-123\""," tells a reader nothing about how long the key is retained. Pair every non-obvious example with a ",[603,1953,810],{},".",[635,1956,1958],{"id":1957},"faq","FAQ",[590,1960,1961,1964,1966,1967,1969],{},[593,1962,1963],{},"What is the difference between Field(examples=...) and openapi_examples?",[603,1965,605],{}," attaches a list of sample values to one property inside the JSON Schema, so it travels with the model everywhere the model is referenced. ",[603,1968,617],{}," attaches named, described examples to one request body of one operation, and it is what fills the Examples dropdown in Swagger UI.",[590,1971,1972,1975,1976,1978],{},[593,1973,1974],{},"Why does my model-level example not appear in the request body dropdown?","\nBecause a route-level ",[603,1977,821],{}," mapping takes precedence for that operation's request body. The model example is still in the document and still renders wherever the model is shown, including the response sample, but the dropdown shows the named route examples instead.",[590,1980,1981,1984],{},[593,1982,1983],{},"Do examples affect validation?","\nNo. Examples are documentation metadata only — Pydantic never validates an example against the model, and an example that would fail validation still ships. That is worth knowing, because it means a stale example produces confidently wrong docs rather than an error.",[590,1986,1987,1990],{},[593,1988,1989],{},"Where should I put examples so they stay accurate?","\nOn the model, next to the fields and constraints they illustrate, so that anyone changing the field sees the example in the same diff. Examples written in separate documentation drift within a release or two.",[590,1992,1993,1996,1997,1999],{},[593,1994,1995],{},"Can I have several named examples for one endpoint?","\nYes, that is exactly what ",[603,1998,617],{}," is for. Each entry has a summary, an optional description and a value, and Swagger UI renders them as a dropdown so a reader can load a realistic payload — including one that deliberately fails — into Try it out.",[635,2001,2003],{"id":2002},"related-reading","Related Reading",[597,2005,2006,2014,2020,2025,2032],{},[600,2007,2008,2011,2012,1954],{},[593,2009,2010],{},"Up to the topic:"," ",[629,2013,632],{"href":631},[600,2015,2016,2017,1954],{},"Broader control over the generated document: ",[629,2018,49],{"href":2019},"\u002Fadvanced-pydantic-validation-serialization\u002Fjson-schema-customization\u002Fcustomizing-openapi-schema-generation-in-fastapi\u002F",[600,2021,2022,2023,1954],{},"One named example per variant of a tagged body: ",[629,2024,1920],{"href":1919},[600,2026,2027,2028,1954],{},"Grouping the documented operations so the examples are findable: ",[629,2029,2031],{"href":2030},"\u002Fcore-architecture-routing-patterns\u002Fmodular-router-organization\u002Frouter-tags-and-openapi-grouping\u002F","Router Tags and OpenAPI Grouping",[600,2033,2034,2035,1954],{},"The constraints your examples illustrate: ",[629,2036,2038],{"href":2037},"\u002Fadvanced-pydantic-validation-serialization\u002Fcustom-validators-field-constraints\u002F","Custom Validators and Field Constraints",[2040,2041,2042],"style",{},"html pre.shiki code .sYEJz, html code.shiki .sYEJz{--shiki-default:#032563}html pre.shiki code .sTJeM, html code.shiki .sTJeM{--shiki-default:#A0111F}html pre.shiki code .sigWx, html code.shiki .sigWx{--shiki-default:#0E1116}html pre.shiki code .sV4o_, html code.shiki .sV4o_{--shiki-default:#702C00}html pre.shiki code .sacAq, html code.shiki .sacAq{--shiki-default:#023B95}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html pre.shiki code .s3dhs, html code.shiki .s3dhs{--shiki-default:#622CBC}html pre.shiki code .sFeEa, html code.shiki .sFeEa{--shiki-default:#66707B}",{"title":843,"searchDepth":856,"depth":856,"links":2044},[2045,2046,2047,2050,2051,2052,2053],{"id":637,"depth":856,"text":638},{"id":769,"depth":856,"text":770},{"id":832,"depth":856,"text":833,"children":2048},[2049],{"id":1594,"depth":873,"text":1595},{"id":1641,"depth":856,"text":1642},{"id":1897,"depth":856,"text":1898},{"id":1957,"depth":856,"text":1958},{"id":2002,"depth":856,"text":2003},"2026-07-20","Add examples to FastAPI docs three ways: Field(examples=[...]), json_schema_extra and Body(openapi_examples), and see where each one surfaces in Swagger UI.","md",[2058,2060,2062,2064,2066],{"q":1963,"a":2059},"Field(examples=[...]) attaches a list of sample values to one property inside the JSON Schema, so it travels with the model everywhere the model is referenced. Body(openapi_examples={...}) attaches named, described examples to one request body of one operation, and it is what fills the Examples dropdown in Swagger UI.",{"q":1974,"a":2061},"Because a route-level openapi_examples mapping takes precedence for that operation's request body. The model example is still in the document and still renders wherever the model is shown, including the response sample, but the dropdown shows the named route examples instead.",{"q":1983,"a":2063},"No. Examples are documentation metadata only — Pydantic never validates an example against the model, and an example that would fail validation still ships. That is worth knowing, because it means a stale example produces confidently wrong docs rather than an error.",{"q":1989,"a":2065},"On the model, next to the fields and constraints they illustrate, so that anyone changing the field sees the example in the same diff. Examples written in separate documentation drift within a release or two.",{"q":1995,"a":2067},"Yes, that is exactly what Body(openapi_examples={...}) is for. Each entry has a summary, an optional description and a value, and Swagger UI renders them as a dropdown so a reader can load a realistic payload — including one that deliberately fails — into Try it out.",null,{"slug":2070,"breadcrumb":2071},"examples-in-openapi-schema",[2072,2075,2078,2079],{"label":2073,"path":2074},"Home","\u002F",{"label":2076,"path":2077},"Advanced Pydantic Validation & Serialization","\u002Fadvanced-pydantic-validation-serialization\u002F",{"label":632,"path":631},{"label":2080,"path":2081},"Examples in the OpenAPI Schema","\u002Fadvanced-pydantic-validation-serialization\u002Fjson-schema-customization\u002Fexamples-in-openapi-schema\u002F",{"title":61,"description":2055},"article","6gzfgCBYvvx8ZBc0e34STmLRKE-9x5_LWJ2lg5wI0JI",[2068,2068],1784588202620]