Not required (optional) fields in multipart/form-data don't have types in swagger about flask-openapi3

[luolingchun]

I got it.

This issue as same as the #128 that will be fix by #129.

[luolingchun]

I can't reproduce your problem, please paste your code.

[fluffybrain3]

This worked in the previous version (doesn't work in this one)

class UploadFileForm(BaseModel):
    file: Optional[FileStorage]
    # other fields

It was changed by the bump-pydantic to

class UploadFileForm(BaseModel):
    file: Optional[FileStorage] = None
    # other fields

and still doesn't work.

Standard case when the field is required works fine for me:

class UploadFileForm(BaseModel):
    file: FileStorage
    # other fields

So I am not able to declare a Form field which is not required and is None by default (Field definition 4) according to the Pydantic docs here
https://docs.pydantic.dev/latest/migration/#required-optional-and-nullable-fields
because then there will be no field types in swagger.

[luolingchun]

f7 can solve your problem.

[fluffybrain3]

I don't understand how f7 solves the problem.
I will try to explain in a different way.
It is not possible to declare a Form field which at the same time:

1. Is not required
2. Has correct type shown in swagger.

When you use f7 you only achieve the 1st point and the field in swagger is just a text input for the FileStorage, boolean, etc.

[luolingchun]

You misunderstood, use file: FileStorage = None, not file: Any= None.

[fluffybrain3]

Okay, so it seems like file: FileStorage = None is the only type that works the way you describe, but others don't.
It doesn't even look like a correct field definition based on these Pydantic docs.

class RequestForm(BaseModel):
    file: FileStorage = None
    some_text: str = None
    some_bool: bool = None

I mean the issue is just that the Field Definition 4 (and 5) in Form is not properly parsed/translated by the flask-openapi3 and because of that it doesn't show a correct input type in swagger.
I see that the same problem happens with Query and Path models.

[fluffybrain3]

@luolingchun I updated to v3.0.1 and this problems still exists.

[luolingchun]

@fluffybrain3 It's worked for me!

from pydantic import BaseModel

from flask_openapi3 import OpenAPI, FileStorage

app = OpenAPI(__name__)


class RequestForm(BaseModel):
    file: FileStorage = None
    some_text: str = None
    some_bool: bool = None


@app.post('/upload/file')
def upload_file(form: RequestForm):
    print(form)

    return {"code": 0, "message": "ok"}


if __name__ == '__main__':
    app.run(debug=True)

[fluffybrain3]

Okay, now it's possible to declare a not required field in a Form this way.
But if you add the Optional type hint, it doesn't work.
According to the Pydantic docs, not required fields should be declared with the Optional.
Without the Optional you cannot tick the "Send empty value" for e.g. int, bool types, because it will throw an error "Input should be a valid boolean, unable to interpret input" which doesn't happen after adding Optional.

class RequestForm(BaseModel):
    file: Optional[FileStorage] = None
    some_text: Optional[str] = None
    some_bool: Optional[bool] = None

[luolingchun]

class RequestForm(BaseModel):
    file: FileStorage = None
    some_text: str = None
    some_bool: Optional[bool] = None

Adding Optional will add an additional type "type": "null".

I don't think Swagger UI is ready for this yet. Or rather, there is no need for multi type support.

Therefore, the best solution currently is not to use Optional and not to send empty value.

"RequestForm": {
    "properties": {
        "file": {
            "format": "binary",
            "title": "File",
            "type": "string"
        },
        "some_bool": {
            "anyOf": [
                {
                    "type": "boolean"
                },
+               {
+                   "type": "null"
+               }
            ],
            "title": "Some Bool"
        },
        "some_text": {
            "title": "Some Text",
            "type": "string"
        }
    },
    "title": "RequestForm",
    "type": "object"
}

[fluffybrain3]

In flask-openapi3 v2.5.4

some_bool: Optional[bool]
some_bool: Optional[bool] = None

were parsed like this

"some_bool": {
    "title": "Some Bool",
    "type": "boolean"
}

Version 3.0.0 changed it to

"some_bool": {
    "anyOf": [
        {
            "type": "boolean"
        },
        {
            "type": "null"
        }
    ],
    "title": "Some Bool"
}

So, was that change intentional?
I would say that the previous version was more practical.

[fluffybrain3]

I discovered another problem with Optional in v3 that didn't occur in v2.

from typing import Optional
from uuid import UUID

from flask_openapi3 import OpenAPI
from pydantic import BaseModel

app = OpenAPI(__name__)


class RequestQuery(BaseModel):
    entity_ids: Optional[list[UUID]] = None


@app.post('/entities')
def upload_file(query: RequestQuery):
    print(query)

    return {"code": 0, "message": "ok"}


if __name__ == '__main__':
    app.run(debug=True)

After changing POST to GET it looks like this

There is definitely something wrong with Optional in v3.

[luolingchun]

Pydantic v2 and OpenAPI 3.1 both follow JSON schema specification draft 2020-12.

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#data-types

https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00#section-4.2.1

Here is an issue in Pydantic v2: pydantic/pydantic#5394 (comment)

Overall, {"type": "null"} is a newly supported type.

Option[bool] and Union[None, bool] are the same, generating the same JSON schema.

"anyOf": [
        {
            "type": "boolean"
        },
        {
            "type": "null"
        }
    ]

How about Union[None, bool, str, int, ...]? That will be generating more types, Swagger UI cannot handle it.

In summary, this is the reason for the problem.

Therefore, we need to avoid using multiple types in the form (application/form) but can use them in the body (application/json).