Fastapi: Impossible to set examples for enums?

Created on 31 Jul 2020 · 4Comments · Source: tiangolo/fastapi

Example

Here's a self-contained, minimal, reproducible, example with my use case:

from enum import Enum

from fastapi import FastAPI, Query

app = FastAPI()


class SomeValue(str, Enum):
    a = 'a'
    b = 'b'


@app.get("/")
def read_root(query_value: SomeValue = Query(..., example='b')):
    # Doesnt matter what happens here
    return {"Hello": "World"}

Description

I set an example for query_value but in the openapi-schema this example is ignored and doesn't appear.
Is that intended or a bug? I need to set a specific example for every parameter (as required by our testsuite) and I don't see why it shouldn't be allowed to set one for enums.

Environment

OS: Windows 10
FastAPI Version 0.60.1
Python version: 3.8

question

Source

jeremyschiemann

Most helpful comment

found a workaround

from enum import Enum

from fastapi import FastAPI, Query

app = FastAPI()


class SomeValue(str, Enum):
    a = 'a'
    b = 'b'

    @classmethod
    def __modify_schema__(cls, field_schema):
        # __modify_schema__ should mutate the dict it receives in place,
        # the returned value will be ignored
        field_schema.update(
            example='b',
        )


@app.get("/")
def read_root(query_value: SomeValue):
    # Doesnt matter what happens here
    return {"Hello": "World"}

jeremyschiemann on 4 Aug 2020

👍3

All 4 comments

There are imports missing on the minimal example :sleeping:
Only the body example appears in the possible responses field. You already have the possible values in the query field, so I don't understand exactly the reason why you need it for your testsuit. Do you mind explaining?

Kludex on 31 Jul 2020

I'm sorry for the missing imports, I edited it.

We have a guideline that every parameters needs an example and our testsuit has a test where it explicitly tests each endpoint with its examples (which it gets from the created /openapi.json).
This is because we need to provide an example endpoint call that 100% works, otherwise the ui designers are complaining.

I understand that for enums all possible values are already present but I don't understand why examples for enums are removed.

Before we where using connexion where you have to write the openapi spec yourself in a yaml, where setting an example for a enum was no problem.

see also the first example for 'Parameter Examples' in 'Adding Examples' of the swagger docu: https://swagger.io/docs/specification/adding-examples/#Parameter_Examples

jeremyschiemann on 31 Jul 2020

found a workaround

from enum import Enum

from fastapi import FastAPI, Query

app = FastAPI()


class SomeValue(str, Enum):
    a = 'a'
    b = 'b'

    @classmethod
    def __modify_schema__(cls, field_schema):
        # __modify_schema__ should mutate the dict it receives in place,
        # the returned value will be ignored
        field_schema.update(
            example='b',
        )


@app.get("/")
def read_root(query_value: SomeValue):
    # Doesnt matter what happens here
    return {"Hello": "World"}

jeremyschiemann on 4 Aug 2020

👍3

Thanks for the help here @Kludex ! :clap: :bow:

Thanks for reporting back and closing the issue :+1: