Add an fully documented api as example

[mircohacker]

Add a new documentation page which displays an example with a fully documented API.

Closes #995

Should a test be implemented as well?

Feedback is welcome.

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Comparison is base (cf73051) 100.00% compared to head (89a0225) 100.00%. Report is 1036 commits behind head on master.

:exclamation: Current head 89a0225 differs from pull request most recent head 8416c15. Consider uploading reports for the commit 8416c15 to get more accurate results

Additional details and impacted files

@@            Coverage Diff            @@
##            master     #1519   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files          540       540           
  Lines        13969     13951   -18     
=========================================
- Hits         13969     13951   -18     

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

[pawamoy]

Hey @mircohaug, this is great! I was going to start working on this and just saw you opened this PR 3 days ago.

This is a very good start! It still misses important parts though, like documentation for possible responses.

Here is an example, if I read the docs correctly. Maybe there's a better way though.

@app.get(
    "/my_route",
    response_model=MyModel,
    responses={
        200: {
            "description": "Success",
            "content": {
                "application/json": {
                    "example": {
                        "my_field_1": "my_value_1",
                        "my_field_2": "my_value_2",
                        "my_field_3": [{"more_json_contents": 0.9842327805523402, "lang": "fra"}]
                    }
                }
            }
        },
        401: {
            "description": "Access denied",
            "content": {
                "application/json": {
                    "example": {
                        "details": "User X does not have permission Y"
                    }
                }
            }
        },
    },
    tags=["my_tag"]
)

[pawamoy]

There also are examples for body param (and maybe other types of params):

Body(
    ...,
    example={
        "model_name": "model1.sav",
        "text": "some text to process",
        "preprocessing": "true"
    }
)

I'll continue to add the things I find in this discussion 🙂

[pawamoy]

If you don't have a custom pydantic model, you can also customize a response class like this:

from starlette.responses import Response

@app.get("status/", response_class=Response(content="Status", media_type="string"))

[mircohacker]

@pawamoy i added example values and schema definitions. But I do not get your last two comments

[mircohacker]

Ping @yankeexe is there more to be done from your side?

[yankeexe]

Ping @yankeexe is there more to be done from your side?

Nope, that was I guess.

[pawamoy]

@mircohaug it's alright, we can always add other examples later :slightly_smiling_face:

[CloudZazu]

Thanks for opening this. I was looking for this type of documentation! Took 5 minutes luckily 😺

[mircohacker]

@yankeexe would you mind to merge this?

[camspilly]

Let's merge this!

[mircohacker]

Ping @tiangolo ready to merge

[pawamoy]

@mircohaug any chance you could review @tupui's suggestions?

[github-actions[bot]]

📝 Docs preview for commit 89a0225c8e23cb6b5cf0ee71f9d0a0869a6b1c7d at: https://631e12709e1ad245d8a7b089--fastapi.netlify.app

[github-actions[bot]]

📝 Docs preview for commit 8416c15e2712f8a9800db3f32c29d8566abda6bb at: https://639cd33835b7d316a2797633--fastapi.netlify.app