Skip to content

Schemas

EmptySchema

Bases: Schema

An empty schema used to generate empty response/schema.

Version changed: 3.0.0

  • Removed from docs and should only be used internally. Use {} instead.
Source code in apiflask/schemas.py 
53
54
55
56
57
58
59
60
61
class EmptySchema(Schema):
    """An empty schema used to generate empty response/schema.

    *Version changed: 3.0.0*

    - Removed from docs and should only be used internally. Use `{}` instead.
    """

    pass

FileSchema

Bases: Schema

A schema for file response.

This is used to represent a file response in OpenAPI spec. If you want to embed a file as base64 string in the JSON body, you can use the apiflask.fields.File field instead.

Example:

from apiflask.schemas import FileSchema
from flask import send_from_directory

@app.get('/images/<filename>')
@app.output(
    FileSchema(type='string', format='binary'),
    content_type='image/png',
    description='An image file'
)
@app.doc(summary="Returns the image file")
def get_image(filename):
    return send_from_directory(app.config['IMAGE_FOLDER'], filename)

The output OpenAPI spec will be:

paths:
/images/{filename}:
  get:
    summary: Returns the image file
    responses:
      '200':
        description: An image file
        content:
          image/png:
            schema:
              type: string
              format: binary

Version Added: 2.0.0

Source code in apiflask/schemas.py 
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
class FileSchema(Schema):
    """A schema for file response.

    This is used to represent a file response in OpenAPI spec. If you want to
    embed a file as base64 string in the JSON body, you can use the
    `apiflask.fields.File` field instead.

    Example:

    ```python
    from apiflask.schemas import FileSchema
    from flask import send_from_directory

    @app.get('/images/<filename>')
    @app.output(
        FileSchema(type='string', format='binary'),
        content_type='image/png',
        description='An image file'
    )
    @app.doc(summary="Returns the image file")
    def get_image(filename):
        return send_from_directory(app.config['IMAGE_FOLDER'], filename)
    ```

    The output OpenAPI spec will be:

    ```yaml
    paths:
    /images/{filename}:
      get:
        summary: Returns the image file
        responses:
          '200':
            description: An image file
            content:
              image/png:
                schema:
                  type: string
                  format: binary
    ```

    *Version Added: 2.0.0*
    """

    def __init__(self, *, type: str = 'string', format: str = 'binary') -> None:
        """
        Arguments:
            type: The type of the file. Defaults to `string`.
            format: The format of the file, one of `binary` and `base64`. Defaults to `binary`.
        """
        self.type = type
        self.format = format

    def __repr__(self) -> str:
        return f'schema: \n  type: {self.type}\n  format: {self.format}'

__init__(*, type='string', format='binary')

Parameters:

Name Type Description Default
type str

The type of the file. Defaults to string.

 'string'
format str

The format of the file, one of binary and base64. Defaults to binary.

 'binary'
Source code in apiflask/schemas.py 
136
137
138
139
140
141
142
143
def __init__(self, *, type: str = 'string', format: str = 'binary') -> None:
    """
    Arguments:
        type: The type of the file. Defaults to `string`.
        format: The format of the file, one of `binary` and `base64`. Defaults to `binary`.
    """
    self.type = type
    self.format = format

PaginationModel

Bases: BaseModel

A model for common pagination information.

Source code in apiflask/schemas.py 
78
79
80
81
82
83
84
85
86
87
88
89
class PaginationModel(BaseModel):
    """A model for common pagination information."""

    page: int
    per_page: int
    pages: int
    total: int
    current: t.Union[AnyUrl, t.Literal['']]
    next: t.Union[AnyUrl, t.Literal['']]
    prev: t.Union[AnyUrl, t.Literal['']]
    first: t.Union[AnyUrl, t.Literal['']]
    last: t.Union[AnyUrl, t.Literal['']]

PaginationSchema

Bases: Schema

A schema for common pagination information.

Source code in apiflask/schemas.py 
64
65
66
67
68
69
70
71
72
73
74
75
class PaginationSchema(Schema):
    """A schema for common pagination information."""

    page = Integer()
    per_page = Integer()
    pages = Integer()
    total = Integer()
    current = URL()
    next = URL()
    prev = URL()
    first = URL()
    last = URL()

Schema

Bases: Schema

A base schema for all schemas. Equivalent to marshmallow.Schema.

Version Added: 1.2.0

Source code in apiflask/schemas.py 
44
45
46
47
48
49
50
class Schema(BaseSchema):
    """A base schema for all schemas. Equivalent to `marshmallow.Schema`.

    *Version Added: 1.2.0*
    """

    pass

External documentation

marshmallow Documentation

Check out the API docs for Schema class in the marshmallow docs:

Pydantic Documentation

For Pydantic models, see: