Automatic status code and response type detection

[angel-langdon]

First Check

• [X] I added a very descriptive title to this issue.
• [X] I used the GitHub search to find a similar issue and didn't find it.
• [X] I searched the FastAPI documentation, with the integrated search.
• [X] I already searched in Google "How to X in FastAPI" and didn't find any information.
• [X] I already read and followed all the tutorial in the docs and didn't find an answer.
• [X] I already checked if it is not related to FastAPI but to Pydantic.
• [X] I already checked if it is not related to FastAPI but to Swagger UI.
• [X] I already checked if it is not related to FastAPI but to ReDoc.

Commit to Help

• [X] I commit to help with one of those options 👆

Example Code

from fastapi import FastAPI, Response

app = FastAPI()


@app.get("/{option}")
def read_root(option: int):
    if option == 1:
        return Response(status_code=200)
    if option == 2:
        return Response(status_code=201)
    return Response(status_code=204)

Description

• Open de browser and go to localhost:8000/docs
• Docs do not show correct response status codes:

Wanted Solution

I would like that FastAPI could automatically detect Response status code and response type

Wanted Code

# Using the same code above but it produces correct documented endpoint

Alternatives

No response

Operating System

macOS

Operating System Details

No response

FastAPI Version

0.78.0

Python Version

3.10.4

Additional Context

No response

[JarroVGIT]

It’s highly unlikely this will ever come to be, as it is pretty hard to know what kind of output types an arbitrary function can have.

[iudeen]

I don't think this goes my what OpenAPI standards offer.

I think you need to describe your various responses explicitly (not automated) in your documentation.

More on this here

[angel-langdon]

It’s highly unlikely this will ever come to be, as it is pretty hard to know what kind of output types an arbitrary function can have.

@JarroVGIT In a repository that has typed variables (type hints) it should be easy. Otherwise, responses could be Unknown or typing.Any by default if the endpoints don't have typing hints in their variables.

I think you need to describe your various responses explicitly (not automated) in your documentation.

I know I can describe my responses explicitly, but I would like it to be automated

[JarroVGIT]

@JarroVGIT In a repository that has typed variables (type hints) it should be easy. Otherwise, responses could be Unknown or typing.Any by default if the endpoints don't have typing hints in their variables.

I would beg the differ. This would require static type checking, and that is anything but a easy endeavor. But if you think it is very doable, feel free to create a PR.

[Kludex]

I can tell you how to implement this, but it's not trivial... 🤷‍♂️

I can tell you for sure that this will never be merged on FastAPI, because it involves doing static type analysis, which is out of scope. Also, it's a lot of work, and it can be an external package.

How you can implement this:

1. You need to traverse the AST (or CST if using libcst) of the whole source code, and map all calls that are being made in the code. You need to do this because from an endpoint function you can have function calls (or any other structure that performs calls, methods, class constructor, etc) that return the Response you want... and that can be recursive as you can have a function calling another function and only then having a return Response...
2. After that, you need to make sure that you need to traverse the AST starting from the endpoint functions. You need to follow two paths: dependencies and function body. Any response returned on those needs to be stored... When you find a call, you go to your map from step 1, and traverse that node as well...
3. At the end of step 2 you're going to have the list of Responses from each endpoint function. Maybe some dynamic programing on functions and possible responses can speed up a bit if the source code is huge (may not be an issue now).

In any case... I'm going to work on this idea at some point, mainly for HTTPExceptions tho. I already have this: https://github.com/Kludex/fastapi-responses, but it doesn't follow the instructions above, it currently implements a very naive approach.