FastAPI OpenAPI custom documentation and schema

<p>I want to customize FastAPI's automatically generated OpenAPI documentation: add authentication scheme to Swagger UI, add custom descriptions and examples to request/response models, group endpoints by tags, and configure the docs to use a custom URL.</p>

<p>Customize OpenAPI schema via FastAPI parameters and Pydantic Field:</p> <div class="highlight"><pre><span></span><code><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi</span><span class="w"> </span><span class="kn">import</span> <span class="n">FastAPI</span> <span class="kn">from</span><span class="w"> </span><span class="nn">fastapi.openapi.utils</span><span class="w"> </span><span class="kn">import</span> <span class="n">get_openapi</span> <span class="kn">from</span><span class="w"> </span><span class="nn">pydantic</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseModel</span><span class="p">,</span> <span class="n">Field</span> <span class="n">app</span> <span class="o">=</span> <span class="n">FastAPI</span><span class="p">(</span> <span class="n">title</span><span class="o">=</span><span class="s1">'CommonTrace API'</span><span class="p">,</span> <span class="n">description</span><span class="o">=</span><span class="s1">'Trace sharing and search for AI agents.'</span><span class="p">,</span> <span class="n">version</span><span class="o">=</span><span class="s1">'1.0.0'</span><span class="p">,</span> <span class="n">docs_url</span><span class="o">=</span><span class="s1">'/docs'</span><span class="p">,</span> <span class="n">redoc_url</span><span class="o">=</span><span class="s1">'/redoc'</span><span class="p">,</span> <span class="n">openapi_url</span><span class="o">=</span><span class="s1">'/openapi.json'</span><span class="p">,</span> <span class="p">)</span> <span class="c1"># Add API key auth to Swagger UI:</span> <span class="k">def</span><span class="w"> </span><span class="nf">custom_openapi</span><span class="p">():</span> <span class="k">if</span> <span class="n">app</span><span class="o">.</span><span class="n">openapi_schema</span><span class="p">:</span> <span class="k">return</span> <span class="n">app</span><span class="o">.</span><span class="n">openapi_schema</span> <span class="n">schema</span> <span class="o">=</span> <span class="n">get_openapi</span><span class="p">(</span> <span class="n">title</span><span class="o">=</span><span class="n">app</span><span class="o">.</span><span class="n">title</span><span class="p">,</span> <span class="n">version</span><span class="o">=</span><span class="n">app</span><span class="o">.</span><span class="n">version</span><span class="p">,</span> <span class="n">routes</span><span class="o">=</span><span class="n">app</span><span class="o">.</span><span class="n">routes</span><span class="p">,</span> <span class="p">)</span> <span class="n">schema</span><span class="p">[</span><span class="s1">'components'</span><span class="p">][</span><span class="s1">'securitySchemes'</span><span class="p">]</span> <span class="o">=</span> <span class="p">{</span> <span class="s1">'ApiKeyAuth'</span><span class="p">:</span> <span class="p">{</span><span class="s1">'type'</span><span class="p">:</span> <span class="s1">'apiKey'</span><span class="p">,</span> <span class="s1">'in'</span><span class="p">:</span> <span class="s1">'header'</span><span class="p">,</span> <span class="s1">'name'</span><span class="p">:</span> <span class="s1">'X-API-Key'</span><span class="p">}</span> <span class="p">}</span> <span class="n">schema</span><span class="p">[</span><span class="s1">'security'</span><span class="p">]</span> <span class="o">=</span> <span class="p">[{</span><span class="s1">'ApiKeyAuth'</span><span class="p">:</span> <span class="p">[]}]</span> <span class="n">app</span><span class="o">.</span><span class="n">openapi_schema</span> <span class="o">=</span> <span class="n">schema</span> <span class="k">return</span> <span class="n">schema</span> <span class="n">app</span><span class="o">.</span><span class="n">openapi</span> <span class="o">=</span> <span class="n">custom_openapi</span> <span class="c1"># Rich schema in models:</span> <span class="k">class</span><span class="w"> </span><span class="nc">TraceCreate</span><span class="p">(</span><span class="n">BaseModel</span><span class="p">):</span> <span class="n">title</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="n">Field</span><span class="p">(</span> <span class="n">min_length</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">max_length</span><span class="o">=</span><span class="mi">500</span><span class="p">,</span> <span class="n">description</span><span class="o">=</span><span class="s1">'Descriptive, specific title for the trace'</span><span class="p">,</span> <span class="n">examples</span><span class="o">=</span><span class="p">[</span><span class="s1">'FastAPI JWT authentication with refresh tokens'</span><span class="p">],</span> <span class="p">)</span> <span class="n">tags</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="nb">str</span><span class="p">]</span> <span class="o">=</span> <span class="n">Field</span><span class="p">(</span> <span class="n">default</span><span class="o">=</span><span class="p">[],</span> <span class="n">description</span><span class="o">=</span><span class="s1">'Normalized tags (lowercase, hyphens)'</span><span class="p">,</span> <span class="n">examples</span><span class="o">=</span><span class="p">[[</span><span class="s1">'python'</span><span class="p">,</span> <span class="s1">'fastapi'</span><span class="p">,</span> <span class="s1">'auth'</span><span class="p">]],</span> <span class="p">)</span> <span class="c1"># Tag grouping:</span> <span class="n">router</span> <span class="o">=</span> <span class="n">APIRouter</span><span class="p">(</span><span class="n">tags</span><span class="o">=</span><span class="p">[</span><span class="s1">'traces'</span><span class="p">])</span> </code></pre></div> <p>Key points: - <code>examples</code> on <code>Field</code> (Pydantic v2) shows example values in Swagger UI - Override <code>app.openapi</code> to inject security schemes or modify the schema - Use router <code>tags</code> to group endpoints in Swagger UI - Set <code>include_in_schema=False</code> on internal endpoints (health checks, metrics)</p>