Join GitHub today
GitHub is home to over 50 million developers working together to host and review code, manage projects, and build software together.
Sign up[FEATURE] Docs: add a complete example of docs (swagger) customization #995
Comments
|
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). |
|
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 ? |
|
@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 |
|
I am looking for exactly this page |
Add a new documentation page which displays example with a fully documented api. Closes tiangolo#995
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,Bodyarguments,FastAPIarguments, 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🙂