Extending generated OpenAPI docs (#799)

* Added login endpoint docs

* make format

* Changed login route into multiple examples.

* Added reset password router docs

* Updated /{id} routes for user

* Updated /me routes

* Fixed user already exists response description

* Updated the /register route

* Updated verify routes

* Updated oauth2 endpoints.

* Applied `make format`

* Renamed Authentication methods for getting their openapi schemas

- `get_login_responses_success` -> `get_openapi_login_responses_success`
- `get_logout_responses_success` -> `get_openapi_logout_responses_success`

* Fixed flake8 errors

* Not using `Final` to keep python37 compatibility

Co-authored-by: François Voron <fvoron@gmail.com>

fastapi_users/authentication/jwt.py

@@ -1,9 +1,9 @@
-from typing import Any, Generic, List, Optional
+from typing import Any, Dict, Generic, List, Optional
 
 import jwt
-from fastapi import Response
+from fastapi import Response, status
 from fastapi.security import OAuth2PasswordBearer
-from pydantic import UUID4
+from pydantic import UUID4, BaseModel
 
 from fastapi_users import models
 from fastapi_users.authentication.base import BaseAuthentication
@@ -11,6 +11,11 @@ from fastapi_users.jwt import SecretType, decode_jwt, generate_jwt
 from fastapi_users.manager import BaseUserManager, UserNotExists
 
 
+class JWTLoginResponse(BaseModel):
+    access_token: str
+    token_type: str
+
+
 class JWTAuthentication(
     Generic[models.UC, models.UD], BaseAuthentication[str, models.UC, models.UD]
 ):
@@ -74,7 +79,27 @@ class JWTAuthentication(
         user_manager: BaseUserManager[models.UC, models.UD],
     ) -> Any:
         token = await self._generate_token(user)
-        return {"access_token": token, "token_type": "bearer"}
+        return JWTLoginResponse(access_token=token, token_type="bearer")
+
+    @staticmethod
+    def get_openapi_login_responses_success() -> Dict[str, Any]:
+        return {
+            status.HTTP_200_OK: {
+                "model": JWTLoginResponse,
+                "content": {
+                    "application/json": {
+                        "example": {
+                            "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1"
+                            "c2VyX2lkIjoiOTIyMWZmYzktNjQwZi00MzcyLTg2Z"
+                            "DMtY2U2NDJjYmE1NjAzIiwiYXVkIjoiZmFzdGFwaS"
+                            "11c2VyczphdXRoIiwiZXhwIjoxNTcxNTA0MTkzfQ."
+                            "M10bjOe45I5Ncu_uXvOmVV8QxnL-nZfcH96U90JaocI",
+                            "token_type": "bearer",
+                        }
+                    }
+                },
+            },
+        }
 
     async def _generate_token(self, user: models.UD) -> str:
         data = {"user_id": str(user.id), "aud": self.token_audience}