Flask+Swagger接口文档JWT认证仅支持JWT前缀而非Bearer的解决咨询

Got it, let's fix this Swagger JWT prefix issue for your Flask app. The problem is that Swagger UI defaults to using the Bearer prefix for JWT auth, but your backend expects JWT instead. Here's how you can adjust the configuration depending on which Flask-Swagger extension you're using:

When your Flask backend expects Authorization: JWT <token> instead of the default Bearer prefix, you need to override Swagger's security definition to use the right scheme.

1. For Flask-RESTX (Most Common) #

If you're using Flask-RESTX (the maintained fork of Flask-RESTPlus), you can define a custom security scheme directly in your API setup:

from flask import Flask
from flask_restx import Api, Resource

app = Flask(__name__)

# Define a custom JWT security scheme with the correct prefix
api = Api(
    app,
    title="Your API Title",
    version="1.0",
    description="Your API Description",
    security="jwt",  # Enable this security globally for all endpoints
    authorizations={
        'jwt': {
            'type': 'apiKey',
            'in': 'header',
            'name': 'Authorization',
            'description': 'Enter your JWT token with the **JWT** prefix, e.g. `JWT abc123xyz`'
        }
    }
)

# Example protected resource
@api.route('/protected')
class ProtectedResource(Resource):
    @api.doc(security='jwt')  # Apply to individual endpoints if not using global security
    def get(self):
        return {"message": "Access granted successfully"}

if __name__ == '__main__':
    app.run(debug=True)

The critical part here is the authorizations dictionary: we specify the header name as Authorization, and the description clearly guides users to use the JWT prefix. When users click the "Authorize" button in Swagger UI, they’ll see this instruction, and after entering their token, Swagger will send the header as Authorization: JWT <token> instead of Bearer.

2. For Flask-Swagger-UI #

If you're using the basic flask-swagger-ui extension, you’ll need to customize your Swagger JSON spec to adjust the security scheme:

First, create or update your swagger.json file to include the custom security definition:

{
  "swagger": "2.0",
  "info": {
    "title": "Your API",
    "version": "1.0.0"
  },
  "securityDefinitions": {
    "jwtAuth": {
      "type": "apiKey",
      "name": "Authorization",
      "in": "header",
      "description": "JWT authorization header using the JWT scheme. Example: \"Authorization: JWT {token}\""
    }
  },
  "security": [{"jwtAuth": []}],
  "paths": {
    "/protected": {
      "get": {
        "summary": "Protected endpoint",
        "responses": {
          "200": {
            "description": "Success response"
          }
        }
      }
    }
  }
}

Then, link this custom spec when initializing flask-swagger-ui in your app:

from flask import Flask
from flask_swagger_ui import get_swaggerui_blueprint

app = Flask(__name__)

SWAGGER_URL = '/swagger'
API_URL = '/static/swagger.json'  # Path to your custom swagger spec file

swaggerui_blueprint = get_swaggerui_blueprint(
    SWAGGER_URL,
    API_URL,
    config={
        'app_name': "Your API"
    }
)

app.register_blueprint(swaggerui_blueprint, url_prefix=SWAGGER_URL)

# Example protected route
@app.route('/protected')
def protected():
    return {"message": "Access granted successfully"}

if __name__ == '__main__':
    app.run(debug=True)

Why This Works #

Swagger UI’s default JWT handler uses Bearer because it aligns with OAuth2 standards, but since your backend expects the non-standard JWT prefix, defining a custom API key security scheme lets us explicitly control the header format. This ensures Swagger sends the exact header your backend is configured to accept.

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