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/base.py

@@ -1,4 +1,4 @@
-from typing import Any, Generic, Optional, TypeVar
+from typing import Any, Dict, Generic, Optional, TypeVar
 
 from fastapi import Response
 from fastapi.security.base import SecurityBase
@@ -42,6 +42,11 @@ class BaseAuthentication(Generic[T, models.UC, models.UD]):
     ) -> Any:
         raise NotImplementedError()
 
+    @staticmethod
+    def get_openapi_login_responses_success() -> Dict[str, Any]:
+        """Return a dictionary to use for the openapi responses route parameter."""
+        raise NotImplementedError()
+
     async def get_logout_response(
         self,
         user: models.UD,
@@ -49,3 +54,8 @@ class BaseAuthentication(Generic[T, models.UC, models.UD]):
         user_manager: BaseUserManager[models.UC, models.UD],
     ) -> Any:
         raise NotImplementedError()
+
+    @staticmethod
+    def get_openapi_logout_responses_success() -> Dict[str, Any]:
+        """Return a dictionary to use for the openapi responses route parameter."""
+        raise NotImplementedError()