[Question] Documenting additional responses about flama HOT 3 CLOSED

It's possible to document multiple responses with the current version, but it's up to the developer to do it manually in the docstring of the endpoint:

@app_.route("/endpoint/", methods=["GET"])
async def get(self) -> Puppy:
    """
    description: Puppy.
    responses:
      200:
        description: The puppy.
      404:
        description: Puppy not found
    """
    ...

So I have been working on adding a bit of control over errors and it could be useful for documenting other responses (or at least error responses). I have defined a standard response for errors that includes the error type, status code and a detailed message; the schema used for these responses can be found in starlette_api.responses and it's automatically included in OpenAPI schema as a component, and by default all endpoints will generate a default response that specifies this schema is used for unexpected errors. An example using this schema could be:

@app_.route("/endpoint/", methods=["GET"])
async def get(self) -> Puppy:
    """
    description: Puppy.
    responses:
      200:
        description: The puppy.
      404:
        description: Puppy not found
        content:
          application/json:
            schema:
              $ref: #/components/schemas/APIError
    """
    try:
        return get_puppy()
    except PuppyNotFound:
        raise HTTPException(status_code=404, detail="Puppy not found")

Again, it's a bit handcrafted but at least you have an standardize response for all errors in your API.

As a note, when the OpenAPI schema is generated the output schema of the view will be added automatically to the first response code found.

I personally haven't faced the case where your endpoint will return more than one positive response so I didn't even think that it could be useful. If you feel that it would be nice to have it, I'm open to any suggestion :)

from flama.

Thanks for the quick response! I am on board with just the single positive response. I don't see any good reason to have multiple success response types.

I am interested in your standard response for errors. Have you thought of any other way to specify the error types? My first thought was something like this:

@app_.route("/endpoint/", methods=["GET"])
@app_.error_response(404, HttpException, description='Puppy not found')
async def get(self) -> Puppy:
    """
    description: Puppy.
    responses:
      200:
        description: The puppy.
    """
    try:
        return get_puppy()
    except PuppyNotFound:
        raise HTTPException(status_code=404, detail="Puppy not found")

I'm not super familiar with this code base so not sure how much effort this would take, but if you had a use for something like this, I'd be up for helping out where I could. Also, maybe this is overkill, but I do like the idea of something similar.

from flama.

It's possible to implement something like you proposed but my concern is that the first idea in mind I had when started the project was to make the code as much expressive as possible and the schema generation is based on the information of the code itself. What you propose is a decorator that simply adds metadata to the code, but doesn't modify the functionality of the API itself so, under my perspective it adds complexity to the code but doesn't modify it behavior so I'm keen on using the docstring as the source of the endpoints metadata for everything that cannot be inferred from the code.

from flama.