Better explanation of the functions/handlers within the library and their purpose

[karimabedrabbo]

/* the purpose of this function is to stick relevant user identifiers within the jwt token (as token claims)
	after having successfully authenticated (logged in). The data parameter into this function is the return value of the
	authentication handler. If you wish to use these claims within your application, it is under the key "JWT_PAYLOAD" within the gin context (Assuming you are using the
	middlewarefunc provided by the library). Refer to the middlewarefunc description under "AuthenticationMiddleware"
	for more.
*/
func payloadFunc(data interface{}) jwt.MapClaims { }

/*
	The purpose of this function is to literally set the gin context to have "IdentityKey" have the value of the identity
	of the user (from parsing the token, checking the claims, and getting the identity value from the claims).
	The library passes this identity value into the authorizator function as the misleading "data" parameter
	(it's actually just the identity value, probably a uuid or integer depending on your application).
 */
func identityHandler(c *gin.Context) interface{} { }

/*
	Basically it checks that the request passes in a jwt token,
	parses the token, then extracts the claims from that token, and then authorizes the user using the authorization function.
	When the middlewarefunc extracts the claims, it stores them within the gin context under the key "JWT_PAYLOAD" (after having parsed the token
	and authorized the user/token).
*/
func MiddlewareFunc() gin.HandlerFunc { }

/*
	This runs within the middlewarefunc and the purpose of it is to check if the user is legitimately authorized to
	access the api calls (aka checking a role or something like that). The "data" parameter here is actually just
	the identity of the user (uuid or integer or whatever). After the library checks that the token is valid, it runs
	this function to check if the user is authorized to access the endpoints that the middleware is running on.
*/
func authorizator(data interface{}, c *gin.Context) bool { }

/*
	the purpose of this function is to use the http request (using gin context)
	to basically verify the user credentials (password matches hashed password for
	a given user email). Then the authenticator should return the user data that
	you want to stick in the jwt token as claims within the token (definitely the user id
	and probably like the user's name, role, and email/username. In other words,
	the data returned from the authenticator is passed in as a parameter into the payload function
	which is used to create a jwt token (with the relevant user identifiers mentioned above)
	after having successfully authenticated.
 */
func authenticator(c *gin.Context) (i interface{}, e error) { }

Please correct in the comments if I got anything wrong.

PS. Also to answer a tangent question on how to authorize different endpoints for users with different roles, I found the best solution was just to manually make another middleware wrapper (like "SysadminAuthorizerMiddleware") where the normal authorizator runs (which most regular users should pass), and then the SysadminAuthorizerMiddleware runs which uses the claims to check for the "sysadmin" role. Anyways hopes this helps.

[GTANAdam]

I approve, without proper documentation it is quite confusing what each function does.

[theriverman]

I highly support this proposal.
Documentation is quite lacking and I have no clue on many things inside this library.

[appleboy]

@karimabedrabbo Can you send PR to improve the documentation?

[karimabedrabbo]

Done @appleboy