配置¶

基础知识¶

在 Flask 中，配置系统是基于 app.config 属性构建的。它是一个类字典的属性，因此你可以像操作字典一样操作它

app.config 属性将会包含以下配置：

内置于 Flask 的配置变量
内置于 Flask 扩展的配置变量
内置于 APIFlask 的配置变量
你自定义的配置变量

这是 app.config 基本操作的一个示例:

from apiflask import APIFlask

app = APIFlask(__name__)

# 设置一个配置项
app.config['DESCRIPTION'] = 'A wonderful API'

# 读取一个配置项
description = app.config['DESCRIPTION']

因为它是一个类字典的对象，你也可以通过 app.config.get() 方法读取一个带有默认值的配置变量：

my_name = app.config.get('DESCRIPTION', '默认值')

或者通过 app.config.update() 方法同时更新多个值：

app.config.update(
    'DESCRIPTION'='A wonderful API',
    'FOO'='bar',
    'ITEMS_PER_PAGE'=15
)

对于一个大型应用来说，你可以将所有的配置变量存储于一个独立的文件中。例如，可以将它们存储在 settings.py：

MY_CONFIG = 'A wonderful API'
FOO = 'bar'
ITEMS_PER_PAGE = 15

现在，你可以通过 app.config.from_pyfile() 方法来设置配置变量。

from apiflask import APIFlask

app = APIFlask(__name__)

# 设置从 settings.py 导入的所有配置变量
app.config.from_pyfile('settings.py')

阅读 Flask 文档中的 Configuration Handling 一章来了解更多有关配置管理的内容。

Warning

所有的配置变量应当采用全大写的形式

在应用上下文之外读取配置

如果你想在应用上下文之外读取配置变量，你将看见：“在应用上下文之外工作（Working outside of the application context）“ 的错误，这个错误通常在你采用应用工厂时出现。

当你使用应用工厂时，你可以通过在视图函数中使用 current_app.config 来访问配置：

from flask import current_app

@bp.get('/foo')
def foo():
    bar = current_app.config['BAR']

但是，当你定义一个数据 schema 时，一般不会拥有应用上下文，所以你无法使用 current_app。在这种情况下从存储配置变量的模块访问它们：

from apiflask import Schema

from .settings import CATEGORIES  # 导入配置变量

class PetIn(Schema):
    name = String(required=True, validate=Length(0, 10))
    category = String(required=True, validate=OneOf(CATEGORIES))  # 使用配置变量

内置配置变量¶

以下时所有 APIFlask 内置的配置变量：

OpenAPI 字段¶

生成 OpenAPI spec 时会用到 OpenAPI 相关字段的所有配置，它们也将由 API 文档呈现。

`OPENAPI_VERSION`¶

OpenAPI 规范的版本（openapi.openapi）。这个配置也可以通过 app.openapi_version 属性设置。

类型：str
默认值：'3.0.3'
示例：

app.config['OPENAPI_VERSION'] = '3.0.2'

或：

app.openapi_version = '3.0.2'

Version >= 0.4.0

这个配置变量在 0.4.0 版本中添加。

`SERVERS`¶

API 项目的服务器信息（openapi.servers），接受多个服务器信息的字典。这个配置也可以通过 app.servers 属性设置。

类型：List[Dict[str, str]]
默认值：None
示例：

app.config['SERVERS'] = [
    {
        'name': 'Production Server',
        'url': 'http://api.example.com'
    }
]

或：

app.servers = [
    {
        'name': 'Production Server',
        'url': 'http://api.example.com'
    }
]

`TAGS`¶

OpenAPI spec 文档的标签列表（openapi.tags）接受一个字典的列表，你也可以传入一个包含所有标签名字的字符串列表。这个配置也可以通过 app.tags 属性设置。

如果没有设置的话，蓝本的名字将会用作标签，所有定义于蓝本中的端点将会自动被这个标签标记。

类型：Union[List[str], List[Dict[str, str]]]
默认值：None
示例：

简单标签名字列表的示例：

app.config['TAGS'] = ['foo', 'bar', 'baz']

包含标签描述的示例：

app.config['TAGS'] = [
    {'name': 'foo', 'description': 'The description of foo'},
    {'name': 'bar', 'description': 'The description of bar'},
    {'name': 'baz', 'description': 'The description of baz'}
]

包含完整 OpenAPI 标签的示例：

app.config['TAGS'] = [
    {
        'name': 'foo',
        'description': 'tag description',
        'externalDocs': {
            'description': 'Find more info here',
            'url': 'http://example.com'
        }
    }
]

使用 app.tags：

app.tags = ['foo', 'bar', 'baz']

`EXTERNAL_DOCS`¶

API 项目的外部文档信息（openapi.externalDocs），这个配置也可以通过 app.external_docs 属性设置。

类型: Dict[str, str]
默认值: None
示例：

app.config['EXTERNAL_DOCS'] = {
    'description': 'Find more info here',
    'url': 'http://docs.example.com'
}

或:

app.external_docs = {
    'description': 'Find more info here',
    'url': 'http://docs.example.com'
}

`INFO`¶

API 项目的信息字段（openapi.info），这个配置也可以通过 app.info 属性设置，信息对象（openapi.info）接受一个包含以下信息字段的字典：description， termsOfService，contact，license。你可以使用分开的配置变量来覆盖这个字典。

类型: Dict[str, str]
默认值: None
示例：

app.config['INFO'] = {
    'description': '...',
    'termsOfService': 'http://example.com',
    'contact': {
        'name': 'API Support',
        'url': 'http://www.example.com/support',
        'email': 'support@example.com'
    },
    'license': {
        'name': 'Apache 2.0',
        'url': 'http://www.apache.org/licenses/LICENSE-2.0.html'
    }
}

或：

app.info = {
    'description': '...',
    'termsOfService': 'http://example.com',
    'contact': {
        'name': 'API Support',
        'url': 'http://www.example.com/support',
        'email': 'support@example.com'
    },
    'license': {
        'name': 'Apache 2.0',
        'url': 'http://www.apache.org/licenses/LICENSE-2.0.html'
    }
}

`DESCRIPTION`¶

API 项目的描述（openapi.info.description），这个配置也可以通过 app.description 属性设置。

类型: str
默认值: None
示例：

app.config['DESCRIPTION'] = 'Some description of my API.'

或：

app.description = 'Some description of my API.'

`TERMS_OF_SERVICE`¶

API 项目的服务条款 URL（openapi.info.termsOfService），这个配置也可以通过 app.terms_of_service 属性设置。

类型: str
默认值: None
示例：

app.config['TERMS_OF_SERVICE'] = 'http://example.com/terms/'

或：

app.terms_of_service = 'http://example.com/terms/'

`CONTACT`¶

API 项目的联系信息（openapi.info.contact）。这个配置也可以通过 app.contact 设置。

类型: Dict[str, str]
默认值: None
示例：

app.config['CONTACT'] = {
    'name': 'API Support',
    'url': 'http://example.com',
    'email': 'support@example.com'
}

或：

app.contact = {
    'name': 'API Support',
    'url': 'http://example.com',
    'email': 'support@example.com'
}

`LICENSE`¶

API 项目的协议（openapi.info.license），这个配置也可以通过 app.license 设置。

类型: Dict[str, str]
默认值: None
示例：

app.config['LICENSE'] = {
    'name': 'Apache 2.0',
    'url': 'http://www.apache.org/licenses/LICENSE-2.0.html'
}

或：

app.license = {
    'name': 'Apache 2.0',
    'url': 'http://www.apache.org/licenses/LICENSE-2.0.html'
}

OpenAPI spec¶

自定义 OpenAPI spec 的生成。

`SPEC_FORMAT`¶

OpenAPI spec 的格式，接受 'json'、'yaml' 或 'yml'中的一个。这个配置在以下几种情形下使用：

通过内置的路由返回 spec 信息。
在不传入 --format/-f 选项时运行 flask spec 命令。

Warning

APIFlask(spec_path=...) 在 0.7.0 及之后的版本中去除了对格式的自动检测。

类型: str
默认值: 'json'
示例：

app.config['SPEC_FORMAT'] = 'yaml'

Version >= 0.7.0

这个配置变量在 0.7.0 版本中添加。

`LOCAL_SPEC_PATH`¶

OpenAPI spec 文件的路径。

类型: str
默认值: None
示例：

app.config['LOCAL_SPEC_PATH'] = 'openapi.json'

Warning

如果你传入的路径是一个相对路径，请不要在前面添加一个斜杠（/）。

Version >= 0.7.0

这个配置变量在 0.7.0 版本中添加。

`LOCAL_SPEC_JSON_INDENT`¶

本地 OpenAPI spec 在 JSON 格式下的缩进量。

类型: int
默认值: 2
示例：

app.config['LOCAL_SPEC_JSON_INDENT'] = 4

Version >= 0.7.0

这个配置变量在 0.7.0 版本中添加。

`SYNC_LOCAL_SPEC`¶

如果这个配置为 True，那么本地的 spec 文件将会自动同步更新，在保持本地 spec 文件自动同步更新一节中查看示例用法。

类型: bool
默认值: None
示例：

app.config['SYNC_LOCAL_SPEC'] = True

Version >= 0.7.0

这个配置变量在 0.7.0 版本中添加。

`JSON_SPEC_MIMETYPE`¶

用作 OpenAPI spec JSON 响应值的 MIME 类型字符串。

类型: str
默认值: 'application/json'
示例：

app.config['JSON_SPEC_MIMETYPE'] = 'application/custom-json'

Version >= 0.4.0

这个配置变量在 0.4.0 版本中添加。

`YAML_SPEC_MIMETYPE`¶

用作 OpenAPI spec YAML 响应值的 MIME 类型字符串。

类型: str
默认值: 'text/vnd.yaml'
示例：

app.config['YAML_SPEC_MIMETYPE'] = 'text/x-yaml'

Version >= 0.4.0

这个配置变量在 0.4.0 版本中添加。

对自动化行为的控制¶

以下配置变量被用来控制 APIflask 的自动化行为，所有这些配置变量的默认值都是 True，你可以在需要时禁用它们。

`AUTO_TAGS`¶

启用或禁用自动从蓝本名生成标签（openapi.tags）。

Tip

这种自动化行为仅当 app.tags 或 TAGS 配置没有被设置的时候才会进行。

类型: bool
默认值: True
示例：

app.config['AUTO_TAGS'] = False

`AUTO_OPERATION_SUMMARY`¶

启用或禁用自动从视图函数名或文档生成 OpenAPI 中路径的概要（summary）。

Tip

这种自动化行为仅当视图函数没有被 app.doc(summary=...) 装饰时才会进行。

类型: bool
默认值: True
示例：

app.config['AUTO_OPERATION_SUMMARY'] = False

Warning

在 0.8.0 及之后的版本中，这个变量从 AUTO_PATH_SUMMARY 重命名为 AUTO_OPERATION_SUMMARY。

`AUTO_OPERATION_DESCRIPTION`¶

启用或禁用自动从视图函数文档生成 OpenAPI 中对路径的描述。

Tip

这种自动化行为仅当视图函数没有被 @app.doc(description=...) 装饰时才会进行。

类型: bool
默认值: True
示例：

app.config['AUTO_OPERATION_DESCRIPTION'] = False

Warning

在 0.8.0 及之后的版本中，这个变量从 AUTO_PATH_DESCRIPTION 重命名为 AUTO_OPERATION_DESCRIPTION。

`AUTO_OPERATION_ID`¶

Version >= 0.10.0

这个功能在 0.10.0 版本中添加。

启用或禁用自动从视图函数的请求方法和端点处生成 operationId。在设置 operationId 一节中了解详细内容。

类型: bool
默认值: False
示例：

app.config['AUTO_OPERATION_ID'] = True

`AUTO_200_RESPONSE`¶

如果一个视图函数不被 @app.input、@app.output、@app.auth_required、@app.doc 装饰，APIFlask 会默认在 OpenAPI spec 中为这个视图默认添加一个 200 响应。将这个配置设为 False 来禁用这种行为。

Tip

You can change the description of the default 200 response with config SUCCESS_DESCRIPTION.

类型: bool
默认值: True
示例：

app.config['AUTO_200_RESPONSE'] = False

`AUTO_404_RESPONSE`¶

如果一个视图函数的 URL 规则包含一个变量，在默认情况下，APIFlask 会向 OpenAPI spec 中添加一个 404 响应。将这个配置设置为 False 来禁用这种行为。

Tip

你可以通过 NOT_FOUND_DESCRIPTION 配置来改编自动 404 相应的描述

类型: bool
默认值: True
示例：

app.config['AUTO_404_RESPONSE'] = False

Version >= 0.8.0

这个配置变量在 0.8.0 版本中添加。

`AUTO_VALIDATION_ERROR_RESPONSE`¶

如果一个视图函数使用 @app.input 来验证输入的请求数据， APIFlask 会向这个视图的 OpenAPI spec 中添加一个数据验证错误响应。

类型: bool
默认值: True
示例：

app.config['AUTO_VALIDATION_ERROR_RESPONSE'] = False

`AUTO_AUTH_ERROR_RESPONSE`¶

如果一个视图函数使用 @app.auth_required 来限制访问， APIFlask 会向这个视图的 OpenAPI spec 中添加一个安全认证错误。将这个配置设置为 False 来禁用这种行为。

类型: bool
默认值: True
示例：

app.config['AUTO_AUTH_ERROR_RESPONSE'] = False

响应自定义¶

以下配置变量用来自定义自动化响应。

`SUCCESS_DESCRIPTION`¶

状态码为 2XX 的响应的默认描述。

类型: str
默认值: Successful response
示例：

app.config['SUCCESS_DESCRIPTION'] = 'Success!'

Version >= 0.4.0

这个配置变量在 0.4.0 版本中添加。

`NOT_FOUND_DESCRIPTION`¶

状态码为 404 的响应的默认描述。

类型: str
默认值: Not found
示例：

app.config['NOT_FOUND_DESCRIPTION'] = 'Missing'

Version >= 0.8.0

这个配置变量在 0.8.0 版本中添加。

`VALIDATION_ERROR_STATUS_CODE`¶

数据验证错误响应的默认返回值。

类型: int
默认值: 422
示例：

app.config['VALIDATION_ERROR_STATUS_CODE'] = 422

`VALIDATION_ERROR_DESCRIPTION`¶

数据验证错误响应的默认描述 The description of validation error response.

类型: str
默认值: 'Validation error'
示例：

app.config['VALIDATION_ERROR_DESCRIPTION'] = 'Invalid JSON body'

`VALIDATION_ERROR_SCHEMA`¶

数据验证错误响应的 schema。本配置接受一个 schema 类或一个 OpenAPI schema 定义的字典。

类型: Union[Schema, dict]
默认值: apiflask.schemas.validation_error_schema
示例：

app.config['VALIDATION_ERROR_SCHEMA'] = CustomValidationErrorSchema

`AUTH_ERROR_STATUS_CODE`¶

安全认证错误响应的状态码。

类型: int
默认值: 401
示例：

app.config['AUTH_ERROR_STATUS_CODE'] = 403

`AUTH_ERROR_DESCRIPTION`¶

安全认证错误响应的描述。

类型: str
默认值: 'Authentication error'
示例：

app.config['AUTH_ERROR_DESCRIPTION'] = 'Auth error'

`HTTP_ERROR_SCHEMA`¶

通用的 HTTP 错误响应的 schema。本配置接受一个 schema 类或一个 OpenAPI schema 定义的字典。

类型: Union[Schema, dict]
默认值: apiflask.schemas.http_error_schema
示例：

app.config['HTTP_ERROR_SCHEMA'] = CustomHTTPErrorSchema

`BASE_RESPONSE_SCHEMA`¶

基响应的 schema。本配置接受一个 schema 类或一个 OpenAPI schema 定义的字典

类型: Union[Schema, dict]
默认值: None
示例：

from apiflask import APIFlask, Schema
from apiflask.fields import String, Integer, Field

app = APIFlask(__name__)

class BaseResponse(Schema):
    message = String()
    status_code = Integer()
    data = Field()

app.config['BASE_RESPONSE_SCHEMA'] = BaseResponse

Version >= 0.9.0

这个配置变量在 0.9.0 版本中添加。

`BASE_RESPONSE_DATA_KEY`¶

基响应的数据键，它应该与响应 schema 的数据字段名相匹配。 The data key of the base response, it should match the data field name in the base response schema.

类型: str
默认值: 'data'
示例：

app.config['BASE_RESPONSE_DATA_KEY'] = 'data'

Version >= 0.9.0

这个配置变量在 0.9.0 版本中添加。

API documentation¶

以下配置变量被用来自定义 Swagger UI 和 Redoc 文档。

`DOCS_FAVICON`¶

API 文档图标文件的绝对或相对 URL。

类型: str
默认值: 'https://apiflask.com/_assets/favicon.png'
示例：

app.config['DOCS_FAVICON'] = 'https://cdn.example.com/favicon.png'

`REDOC_USE_GOOGLE_FONT`¶

在 Redoc 文档中启用或禁用 Google 字体。

类型: bool
默认值: True
示例：

app.config['REDOC_USE_GOOGLE_FONT'] = False

`REDOC_CONFIG`¶

这个配置项将会传递给 Redoc。在 Redoc documentation 查看可配置项。

类型: dict
默认值: None
示例：

app.config['REDOC_CONFIG'] = {'disableSearch': True, 'hideLoading': True}

Version >= 0.9.0

这个配置变量在 0.9.0 版本中添加。

`REDOC_STANDALONE_JS`¶

Redoc 独立 JavaScript 文件的绝对或相对 URL。

类型: str
默认值: 'https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js'
示例：

app.config['REDOC_STANDALONE_JS'] = 'https://cdn.example.com/filename.js'

`SWAGGER_UI_CSS`¶

Swagger UI CSS 文件的绝对或相对 URL。

类型: str
默认值: 'https://cdn.jsdelivr.net/npm/swagger-ui-dist@3/swagger-ui.css'
示例：

app.config['SWAGGER_UI_CSS'] = 'https://cdn.example.com/filename.js'

`SWAGGER_UI_BUNDLE_JS`¶

Swagger UI JavaScript 打包文件的绝对或相对 URL。

类型: str
默认值: 'https://cdn.jsdelivr.net/npm/swagger-ui-dist@3/swagger-ui-bundle.js'
示例：

app.config['SWAGGER_UI_BUNDLE_JS'] = 'https://cdn.example.com/filename.js'

`SWAGGER_UI_STANDALONE_PRESET_JS`¶

Swagger UI 预设 JavaScript 文件的绝对或相对 URL。

类型: str
默认值: 'https://cdn.jsdelivr.net/npm/swagger-ui-dist@3/swagger-ui-standalone-preset.js'
示例：

app.config['SWAGGER_UI_STANDALONE_PRESET_JS'] = 'https://cdn.example.com/filename.js'

`SWAGGER_UI_LAYOUT`¶

Swagger UI 的布局类型，可选项为'BaseLayout' 和 'StandaloneLayout' 中的一个。

类型: str
默认值: 'BaseLayout'
示例：

app.config['SWAGGER_UI_LAYOUT'] = 'StandaloneLayout'

`SWAGGER_UI_CONFIG`¶

Swagger UI 的配置，这个值将会覆盖已经存在的配置，例如 SWAGGER_UI_LAYOUT。

Tip

查看 Swagger UI 文档的配置一节来获取更多信息。

类型: dict
默认值: None
示例：

app.config['SWAGGER_UI_CONFIG'] = {
    'layout': 'StandaloneLayout'
}

`SWAGGER_UI_OAUTH_CONFIG`¶

Swagger UI OAuth 的配置：

ui.initOAuth(yourConfig)

Tip

在 Swagger UI 文档的 OAuth 2.0 配置 一节查看更多信息。

类型: dict
默认值: None
示例：

app.config['SWAGGER_UI_OAUTH_CONFIG'] = {
    'realm': 'foo'
}

Flask 内置配置变量¶

请参阅 Builtin Configuration Values 来查看 Flask 提供的内置配置变量。

配置¶

基础知识¶

内置配置变量¶

OpenAPI 字段¶

OPENAPI_VERSION¶

SERVERS¶

TAGS¶

EXTERNAL_DOCS¶

INFO¶

DESCRIPTION¶

TERMS_OF_SERVICE¶

CONTACT¶

LICENSE¶

OpenAPI spec¶

SPEC_FORMAT¶

LOCAL_SPEC_PATH¶

LOCAL_SPEC_JSON_INDENT¶

SYNC_LOCAL_SPEC¶

JSON_SPEC_MIMETYPE¶

YAML_SPEC_MIMETYPE¶

对自动化行为的控制¶

AUTO_TAGS¶

AUTO_OPERATION_SUMMARY¶

AUTO_OPERATION_DESCRIPTION¶

AUTO_OPERATION_ID¶

AUTO_200_RESPONSE¶

AUTO_404_RESPONSE¶

AUTO_VALIDATION_ERROR_RESPONSE¶

AUTO_AUTH_ERROR_RESPONSE¶

响应自定义¶

SUCCESS_DESCRIPTION¶

NOT_FOUND_DESCRIPTION¶

VALIDATION_ERROR_STATUS_CODE¶

VALIDATION_ERROR_DESCRIPTION¶

VALIDATION_ERROR_SCHEMA¶

AUTH_ERROR_STATUS_CODE¶

AUTH_ERROR_DESCRIPTION¶

HTTP_ERROR_SCHEMA¶

BASE_RESPONSE_SCHEMA¶

BASE_RESPONSE_DATA_KEY¶

API documentation¶

DOCS_FAVICON¶

REDOC_USE_GOOGLE_FONT¶

REDOC_CONFIG¶

REDOC_STANDALONE_JS¶

SWAGGER_UI_CSS¶

SWAGGER_UI_BUNDLE_JS¶

SWAGGER_UI_STANDALONE_PRESET_JS¶

SWAGGER_UI_LAYOUT¶

SWAGGER_UI_CONFIG¶

SWAGGER_UI_OAUTH_CONFIG¶

Flask 内置配置变量¶

`OPENAPI_VERSION`¶

`SERVERS`¶

`TAGS`¶

`EXTERNAL_DOCS`¶

`INFO`¶

`DESCRIPTION`¶

`TERMS_OF_SERVICE`¶

`CONTACT`¶

`LICENSE`¶

`SPEC_FORMAT`¶

`LOCAL_SPEC_PATH`¶

`LOCAL_SPEC_JSON_INDENT`¶

`SYNC_LOCAL_SPEC`¶

`JSON_SPEC_MIMETYPE`¶

`YAML_SPEC_MIMETYPE`¶

`AUTO_TAGS`¶

`AUTO_OPERATION_SUMMARY`¶

`AUTO_OPERATION_DESCRIPTION`¶

`AUTO_OPERATION_ID`¶

`AUTO_200_RESPONSE`¶

`AUTO_404_RESPONSE`¶

`AUTO_VALIDATION_ERROR_RESPONSE`¶

`AUTO_AUTH_ERROR_RESPONSE`¶

`SUCCESS_DESCRIPTION`¶

`NOT_FOUND_DESCRIPTION`¶

`VALIDATION_ERROR_STATUS_CODE`¶

`VALIDATION_ERROR_DESCRIPTION`¶

`VALIDATION_ERROR_SCHEMA`¶

`AUTH_ERROR_STATUS_CODE`¶

`AUTH_ERROR_DESCRIPTION`¶

`HTTP_ERROR_SCHEMA`¶

`BASE_RESPONSE_SCHEMA`¶

`BASE_RESPONSE_DATA_KEY`¶

`DOCS_FAVICON`¶

`REDOC_USE_GOOGLE_FONT`¶

`REDOC_CONFIG`¶

`REDOC_STANDALONE_JS`¶

`SWAGGER_UI_CSS`¶

`SWAGGER_UI_BUNDLE_JS`¶

`SWAGGER_UI_STANDALONE_PRESET_JS`¶

`SWAGGER_UI_LAYOUT`¶

`SWAGGER_UI_CONFIG`¶

`SWAGGER_UI_OAUTH_CONFIG`¶