Improve OAuth2 API Docs (ory#1499)

doc.go

@@ -41,7 +41,8 @@
 //         tokenUrl: /oauth2/token
 //         flow: accessCode
 //         scopes:
-//           offline: "A scope required when requesting refresh tokens"
+//           offline: "A scope required when requesting refresh tokens (alias for `offline`)"
+//           offline_access: "A scope required when requesting refresh tokens"
 //           openid: "Request an OpenID Connect ID Token"
 //     basic:
 //         type: basic

oauth2/handler.go

@@ -203,7 +203,10 @@ func (h *Handler) LogoutHandler(w http.ResponseWriter, r *http.Request, ps httpr
 //
 // The well known endpoint an be used to retrieve information for OpenID Connect clients. We encourage you to not roll
 // your own OpenID Connect client but to use an OpenID Connect client library instead. You can learn more on this
-// flow at https://openid.net/specs/openid-connect-discovery-1_0.html
+// flow at https://openid.net/specs/openid-connect-discovery-1_0.html .
+//
+// Popular libraries for OpenID Connect clients include oidc-client-js (JavaScript), go-oidc (Golang), and others.
+// For a full list of clients go here: https://openid.net/developers/certified/
 //
 //     Produces:
 //     - application/json
@@ -247,8 +250,10 @@ func (h *Handler) WellKnownHandler(w http.ResponseWriter, r *http.Request) {
 //
 // OpenID Connect Userinfo
 //
-// This endpoint returns the payload of the ID Token, including the idTokenExtra values, of the provided OAuth 2.0 access token.
-// The endpoint implements http://openid.net/specs/openid-connect-core-1_0.html#UserInfo .
+// This endpoint returns the payload of the ID Token, including the idTokenExtra values, of
+// the provided OAuth 2.0 Access Token.
+//
+// For more information please [refer to the spec](http://openid.net/specs/openid-connect-core-1_0.html#UserInfo).
 //
 //     Produces:
 //     - application/json
@@ -372,6 +377,8 @@ func (h *Handler) RevocationHandler(w http.ResponseWriter, r *http.Request) {
 // is neither expired nor revoked. If a token is active, additional information on the token will be included. You can
 // set additional data for a token by setting `accessTokenExtra` during the consent flow.
 //
+// For more information [read this blog post](https://www.oauth.com/oauth2-servers/token-introspection-endpoint/).
+//
 //     Consumes:
 //     - application/x-www-form-urlencoded
 //