跳转至

Schemas

EmptySchema

Bases: Schema

An empty schema used to generate empty response/schema.

For 204 response, you can use this schema to generate an empty response body. For 200 response, you can use this schema to generate an empty response body schema.

Example:

@app.delete('/foo')
@app.output(EmptySchema, status_code=204)
def delete_foo():
    return ''

It equals to use {}:

@app.delete('/foo')
@app.output({}, status_code=204)
def delete_foo():
    return ''
Source code in apiflask/schemas.py 
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
class EmptySchema(Schema):
    """An empty schema used to generate empty response/schema.

    For 204 response, you can use this schema to
    generate an empty response body. For 200 response, you can use this schema
    to generate an empty response body schema.

    Example:

    ```python
    @app.delete('/foo')
    @app.output(EmptySchema, status_code=204)
    def delete_foo():
        return ''
    ```

    It equals to use `{}`:

    ```python
    @app.delete('/foo')
    @app.output({}, status_code=204)
    def delete_foo():
        return ''
    ```
    """

    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 
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
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
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 
152
153
154
155
156
157
158
159
160
161
162
163
164
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

PaginationSchema

Bases: Schema

A schema for common pagination information.

Source code in apiflask/schemas.py 
 96
 97
 98
 99
100
101
102
103
104
105
106
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.

The different between marshmallow's Schema and APIFlask's Schema is that the latter sets set_class to OrderedSet by default.

Version Added: 1.2.0

Source code in apiflask/schemas.py 
54
55
56
57
58
59
60
61
62
63
64
class Schema(BaseSchema):
    """A base schema for all schemas.

    The different between marshmallow's `Schema` and APIFlask's `Schema` is that the latter
    sets `set_class` to `OrderedSet` by default.

    *Version Added: 1.2.0*
    """
    # use ordered set to keep the order of fields
    # can be removed when https://github.com/marshmallow-code/marshmallow/pull/1896 is merged
    set_class = OrderedSet

External documentation

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