如何修改Django Swagger Spectacular默认安全认证名称(jwtauth)

问题描述 #

使用 Django Swagger Spectacular 生成接口文档时，默认生成的安全认证名称为jwtauth，现需要重命名该安全认证项的名称，当前使用Django默认schema与Swagger生成方案，现有settings.py配置如下：

SPECTACULAR_SETTINGS = {
    'TITLE': 'title',
    'VERSION': '1.0.0',
    'SERVE_INCLUDE_SCHEMA': False,
    'CONTACT': {'name':'name','email':'noreplay@gmail.com'},
    'SCHEMA_PATH_PREFIX_TRIM': True,
    'SERVERS': [{'url': env('SWAGGER_SERVER')},],
    'PREPROCESSING_HOOKS': ["custom.url_remover.preprocessing_filter_spec"],  
}

解决方法 #

在现有SPECTACULAR_SETTINGS配置中新增3项配置即可完成自定义命名，不需要修改其他业务代码：

SPECTACULAR_SETTINGS = {
    'TITLE': 'title',
    'VERSION': '1.0.0',
    'SERVE_INCLUDE_SCHEMA': False,
    'CONTACT': {'name':'name','email':'noreplay@gmail.com'},
    'SCHEMA_PATH_PREFIX_TRIM': True,
    'SERVERS': [{'url': env('SWAGGER_SERVER')},],
    'PREPROCESSING_HOOKS': ["custom.url_remover.preprocessing_filter_spec"],
    # 以下为新增配置
    # 1. 关闭默认自动生成的jwtauth安全项
    'DISABLE_DEFAULT_SECURITY_SCHEMES': True,
    # 2. 自定义安全认证组件，键名即为最终展示的认证名称，示例中命名为BearerAuth，可按需修改
    'APPEND_COMPONENTS': {
        'securitySchemes': {
            'BearerAuth': {
                'type': 'http',
                'scheme': 'bearer',
                'bearerFormat': 'JWT',
            }
        }
    },
    # 3. 全局安全配置绑定自定义的认证名称
    'SECURITY': [{'BearerAuth': []}],
}

配置修改完成后，重新执行schema生成命令、重启文档服务即可看到修改后的名称生效。
如果是项目中自定义了Authentication认证类，也可以直接在对应认证类上指定swagger_security_name属性设置名称，优先级高于全局配置。

内容的提问来源于stack exchange，提问作者Deepak Kumar