跳转至

# 模型配置

The BaseModel in Pydantic supports some custom configurations(Model Config), so we can use the `openapi_extra` to extend OpenAPI Specification.

## openapi_extra

The `openapi_extra` will be merged with the automatically generated OpenAPI schema.

### form

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24

    class UploadFilesForm(BaseModel):
        file: FileStorage
        str_list: list[str]

        model_config = dict(
            openapi_extra={
                # "example": {"a": 123},
                "examples": {
                    "Example 01": {
                        "summary": "An example",
                        "value": {
                            "file": "Example-01.jpg",
                            "str_list": ["a", "b", "c"]
                        }
                    },
                    "Example 02": {
                        "summary": "Another example",
                        "value": {
                            "str_list": ["1", "2", "3"]
                        }
                    }
                }
            }
        )

Effect in Redoc:

### body

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28

    class BookBody(BaseModel):
        age: int
        author: str

        model_config = dict(
            openapi_extra={
                "description": "This is post RequestBody",
                "example": {"age": 12, "author": "author1"},
                "examples": {
                    "example1": {
                        "summary": "example summary1",
                        "description": "example description1",
                        "value": {
                            "age": 24,
                            "author": "author2"
                        }
                    },
                    "example2": {
                        "summary": "example summary2",
                        "description": "example description2",
                        "value": {
                            "age": 48,
                            "author": "author3"
                        }
                    }

                }}
        )

Effect in swagger:

You can use `reqiured` in `openapi_extra` to mark the RequestBody as Optional.

    1
    2
    3
    4
    5
    6
    7
    8

    class PingBody(BaseModel):
            ping: str | None = Field("ok", description="String to return, 'ok' when null.")

            model_config = dict(
                openapi_extra = {
                    "required": False
                }
            )

### responses

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22

    class MessageResponse(BaseModel):
        message: str = Field(..., description="The message")

        model_config = dict(
            openapi_extra={
                # "example": {"message": "aaa"},
                "examples": {
                    "example1": {
                        "summary": "example1 summary",
                        "value": {
                            "message": "bbb"
                        }
                    },
                    "example2": {
                        "summary": "example2 summary",
                        "value": {
                            "message": "ccc"
                        }
                    }
                }
            }
        )

Effect in swagger:

## by_alias

Sometimes you may not want to use aliases (such as in the responses model). In that case, `by_alias` will be convenient:

    1
    2
    3
    4
    5
    6
    7

    class MessageResponse(BaseModel):
        message: str = Field(..., description="The message")
        metadata: dict[str, str] = Field(alias="metadata_")

        model_config = dict(
            by_alias=False
        )