Fastapi: [FEATURE] Docs: add a complete example of docs (swagger) customization

[pawamoy]

Maintainers and contributors: thank you very much! 🚀

Is your feature request related to a problem

Currently, the documentation on how to customize the interactive Swagger interface is spread over many different pages, making it difficult to grasp what is possible and how it should be done (response_model, response_class, dicts, routes/decorators arguments, Body arguments, FastAPI arguments, Pydantic models and schemas, docstrings, docstrings markers, etc.).

The auto-generated interactive documentation page is real plus when using FastAPI, so at some point one wants to make it complete with descriptions and examples. Instead of skimming through multiple pages searching for this documentation-related information, it would be absolutely great to have a first-class "Documenting your API" page with a complete example!

I think it would help separating the work for new projects in two clear phases: implementation/experimentation, and refining/completion of the API interface. Once one is comfortable with how documenting is done, both phases can be merged again when adding new functionality.

The solution you would like

Add a page containing a full example of documentation/customization with query, body, cookie parameters examples and descriptions, responses codes, descriptions, examples and content types, tags, main title, main description, main version, etc.

Describe alternatives you've considered

Maybe a good starting point would be to have a page with links pointing to the interesting sections 🙂

[dmontagu]

I personally would be in favor of adding a "table of contents"-style page for OpenAPI-related functionality (and perhaps also other groups of functionality that are spread across different pages).

[tiangolo]

Yeah, I guess that could be okay, although as all FastAPI is built around OpenAPI, it would probably end up having links to almost all the sections in the docs, so, not sure... Then the next issue would be making sure to have it in sync with the docs when they update...

But anyway, would you like to write a PR @pawamoy ?

[pawamoy]

@tiangolo, sure, I'm always willing to resolve the issues I open, though I'm not sure when I'll be able to work on this :slightly_smiling_face:

[mircohaug]

I am looking for exactly this page 🙂 can you provide a quick peek on how to attach descriptions to parameters and model fields. Docstrings at the method level are only set as description of the whole method. Individual documentation of method parameters is not possible this way. If I have this information I could also at least start the docs page.