Update documentation for custom decorators

Author: Landon Gilbert-Bland

docs/custom_decorators.rst

@@ -1,16 +1,13 @@
 Custom Decorators
 =================
 
-NOTE: THIS DOCUMENTATION HAS NOT YET BEEN UPDATED
-
-
 You can create your own decorators that extend the functionality of the
 decorators provided by this extension. For example, you may want to create
 your own decorator that verifies a JWT is present as well as verifying that
-this token has sufficient permissions/roles to access an endpoint.
+the current user is an administrator.
 
 :func:`flask_jwt_extended.verify_jwt_in_request` can be used to build your own decorators.
-This is the same function used the :func:`flask_jwt_extended.jwt_required`.
+This is the same function used by :func:`flask_jwt_extended.jwt_required`.
 
 Here is an example of how this might look.
 

docs/index.rst

@@ -42,7 +42,7 @@ Flask-JWT-Extended's Documentation
    token_locations
    refreshing_tokens
    blocklist_and_token_revoking
-   custom_decorators
-   changing_default_behavior
    options
+   changing_default_behavior
+   custom_decorators
    api

examples/custom_decorators.py

@@ -2,7 +2,6 @@
 
 from flask import Flask
 from flask import jsonify
-from flask import request
 
 from flask_jwt_extended import create_access_token
 from flask_jwt_extended import get_jwt
@@ -15,41 +14,37 @@
 jwt = JWTManager(app)
 
 
-# Here is a custom decorator that verifies the JWT is present in
-# the request, as well as insuring that this user has a role of
-# `admin` in the access token
-def admin_required(fn):
-    @wraps(fn)
-    def wrapper(*args, **kwargs):
-        verify_jwt_in_request()
-        claims = get_jwt()
-        if claims["roles"] != "admin":
-            return jsonify(msg="Admins only!"), 403
-        else:
-            return fn(*args, **kwargs)
-
-    return wrapper
+# Here is a custom decorator that verifies the JWT is present in the request,
+# as well as insuring that the JWT has a claim indicating that this user is
+# an administrator
+def admin_required():
+    def wrapper(fn):
+        @wraps(fn)
+        def decorator(*args, **kwargs):
+            verify_jwt_in_request()
+            claims = get_jwt()
+            if claims["is_administrator"]:
+                return fn(*args, **kwargs)
+            else:
+                return jsonify(msg="Admins only!"), 403
 
+        return decorator
 
-@jwt.additional_claims_loader
-def add_claims_to_access_token(identity):
-    if identity == "admin":
-        return {"roles": "admin"}
-    else:
-        return {"roles": "peasant"}
+    return wrapper
 
 
 @app.route("/login", methods=["POST"])
 def login():
-    username = request.json.get("username", None)
-    access_token = create_access_token(username)
+    access_token = create_access_token(
+        "admin_user", additional_claims={"is_administrator": True}
+    )
     return jsonify(access_token=access_token)
 
 
 @app.route("/protected", methods=["GET"])
-@admin_required
+@admin_required()
 def protected():
-    return jsonify(secret_message="go banana!")
+    return jsonify(foo="bar")
 
 
 if __name__ == "__main__":