doc: show constructor docs and some type improvements

Author: samedii

docs/conf.py

@@ -19,7 +19,7 @@
 
 project = "fastapi-third-party-auth"
 copyright = "2020, Harry M. Winters, Richard Löwenström"
-author = "Harry M. Winters"
+author = "Harry M. Winters, Richard Löwenström"
 
 # The full version, including alpha/beta/rc tags
 release = "0.0.0"
@@ -46,9 +46,17 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "alabaster"
+html_theme = "sphinx_rtd_theme"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path: List[str] = []
+
+autodoc_default_options = {
+    "members": True,
+    "member-order": "bysource",
+    "special-members": "__init__",
+    "undoc-members": True,
+    "exclude-members": "__weakref__",
+}

docs/index.rst

@@ -1,5 +1,5 @@
 Welcome to fastapi-third-party-auth's documentation!
-========================================
+====================================================
 
 Verify and decrypt 3rd party OpenID Connect tokens to protect your
 `FastAPI <https://github.com/tiangolo/fastapi>`_ endpoints.
@@ -87,7 +87,6 @@ Grant Types
 -----------
 .. automodule:: fastapi_third_party_auth.grant_types
    :members:
-   :undoc-members:
 
 IDToken Types
 -------------

fastapi_third_party_auth/auth.py

@@ -11,7 +11,7 @@
     from your_app.auth import auth
 
     @app.get("/auth")
-    def test_auth(authenticated_user: IDToken = Depends(auth.required)):
+    def test_auth(authenticated_user: IDToken = Security(auth.required)):
         return f"Hello {authenticated_user.preferred_username}"
 """
 
@@ -51,7 +51,7 @@ def __init__(
         scopes: List[str] = list(),
         grant_types: List[GrantType] = [GrantType.IMPLICIT],
         signature_cache_ttl: int = 3600,
-        idtoken_model: Type = IDToken,
+        idtoken_model: Type[IDToken] = IDToken,
     ):
         """Configure authentication and use method :func:`require` or :func:`optional`
         to check user credentials.
@@ -117,7 +117,7 @@ def __init__(
             auto_error=False,
         )
 
-    async def __call__(self, request: Request) -> Optional[str]:
+    async def __call__(self, request: Request) -> None:
         return None
 
     def required(
@@ -137,7 +137,7 @@ def required(
                 behind the scenes by Depends.
 
         Return:
-            IDToken: Dictionary with IDToken information
+            IDToken (self.idtoken_model): User information
 
         raises:
             HTTPException(status_code=401, detail=f"Unauthorized: {err}")
@@ -172,7 +172,7 @@ def optional(
                 behind the scenes by Depends.
 
         Return:
-            IDToken: Dictionary with IDToken information
+            IDToken (self.idtoken_model): User information
 
         raises:
             IDToken validation errors
@@ -201,7 +201,7 @@ def authenticate_user(
                 is not authenticated.
 
         Return:
-            IDToken: Dictionary with IDToken information
+            IDToken (self.idtoken_model): User information
 
         raises:
             HTTPException(status_code=401, detail=f"Unauthorized: {err}")

fastapi_third_party_auth/grant_types.py

@@ -2,7 +2,7 @@
 
 
 class GrantType(str, Enum):
-    """Grant types shown in docs."""
+    """Grant types that can be used in the interactive documentation."""
 
     AUTHORIZATION_CODE = "authorization_code"
     CLIENT_CREDENTIALS = "client_credentials"

fastapi_third_party_auth/idtoken_types.py

@@ -14,10 +14,10 @@ class IDToken(BaseModel):
 
     See the specifications here. https://openid.net/specs/openid-connect-core-1_0.html#IDToken
 
-    Attributes:
+    Parameters:
         iss (str): Issuer Identifier for the Issuer of the response.
         sub (str): Subject Identifier.
-        aud (str): Audience(s) that this ID Token is intended for.
+        aud (Union[str, List[str]]): Audience(s) that this ID Token is intended for.
         exp (str): Expiration time on or after which the ID Token MUST NOT be accepted for processing.
         iat (iat): Time at which the JWT was issued.
 

poetry.lock

@@ -28,6 +28,7 @@ types-cachetools = "^0.1.9"
 types-requests = "^2.25.0"
 pre-commit = "^2.13.0"
 uvicorn = "^0.15.0"
+sphinx-rtd-theme = "^1.0.0"
 
 [tool.poetry.extras]
 docs = ["sphinx"]