Changed to class-based apis

Author: MrMatAP

.idea/runConfigurations/mrmat_python_api_flask.xml

@@ -33,12 +33,14 @@
 from flask_migrate import Migrate
 from flask_marshmallow import Marshmallow
 from flask_oidc import OpenIDConnect
+from flask_smorest import Api
 
 __version__ = pkg_resources.get_distribution('mrmat-python-api-flask').version
 db = SQLAlchemy()
 ma = Marshmallow()
 migrate = Migrate()
 oidc = OpenIDConnect()
+api = Api()
 
 dictConfig({
     'version': 1,
@@ -77,7 +79,11 @@ def create_app(config_override=None, instance_path=None):
     Returns: an initialised Flask app object
 
     """
-    app = Flask(__name__, instance_relative_config=True, instance_path=instance_path)
+    app = Flask(__name__,
+                static_url_path='',
+                static_folder='static',
+                instance_relative_config=True,
+                instance_path=instance_path)
 
     #
     # Set configuration defaults. If a config file is present then load it. If we have overrides, apply them
@@ -88,6 +94,20 @@ def create_app(config_override=None, instance_path=None):
     app.config.setdefault('SQLALCHEMY_TRACK_MODIFICATIONS', False)
     app.config.setdefault('OIDC_USER_INFO_ENABLED', True)
     app.config.setdefault('OIDC_RESOURCE_SERVER_ONLY', True)
+    app.config.setdefault('API_TITLE', 'MrMat :: Python :: API :: Flask')
+    app.config.setdefault('API_VERSION', __version__)
+    app.config.setdefault('OPENAPI_VERSION', '3.0.2')
+    app.config.setdefault('OPENAPI_URL_PREFIX', '/apidoc')
+    app.config.setdefault('OPENAPI_JSON_PATH', 'openapi.json')
+    app.config.setdefault('OPENAPI_SWAGGER_UI_PATH', 'swagger')
+    app.config.setdefault('OPENAPI_SWAGGER_UI_URL', 'https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.24.2/')
+    app.config.setdefault('OPENAPI_REDOC_PATH', 'redoc')
+    app.config.setdefault('OPENAPI_REDOC_URL', 'https://rebilly.github.io/ReDoc/releases/latest/redoc.min.js')
+    app.config.setdefault('OPENAPI_RAPIDOC_PATH', 'rapidoc')
+    app.config.setdefault('OPENAPI_RAPIDOC_URL', 'https://unpkg.com/rapidoc/dist/rapidoc-min.js')
+    #app.config.setdefault('OPENAPI_SWAGGER_UI_CONFIG', {
+    #    'oauth2RedirectUrl': 'http://localhost:5000/apidoc/swagger/oauth2-redirect'
+    #})
     if 'FLASK_CONFIG' in os.environ and os.path.exists(os.path.expanduser(os.environ['FLASK_CONFIG'])):
         app.config.from_json(os.path.expanduser(os.environ['FLASK_CONFIG']))
     if config_override is not None:
@@ -113,6 +133,7 @@ def create_app(config_override=None, instance_path=None):
     db.init_app(app)
     migrate.init_app(app, db)
     ma.init_app(app)
+    api.init_app(app)
     if 'OIDC_CLIENT_SECRETS' in app.config.keys():
         oidc.init_app(app)
     else:
@@ -121,15 +142,45 @@ def create_app(config_override=None, instance_path=None):
     #
     # Import and register our APIs here
 
-    from mrmat_python_api_flask.apis.healthz import bp as api_healthz  # pylint: disable=import-outside-toplevel
+    from mrmat_python_api_flask.apis.healthz import api_healthz  # pylint: disable=import-outside-toplevel
     from mrmat_python_api_flask.apis.greeting.v1 import api_greeting_v1  # pylint: disable=import-outside-toplevel
     from mrmat_python_api_flask.apis.greeting.v2 import api_greeting_v2  # pylint: disable=import-outside-toplevel
     from mrmat_python_api_flask.apis.greeting.v3 import api_greeting_v3  # pylint: disable=import-outside-toplevel
     from mrmat_python_api_flask.apis.resource.v1 import api_resource_v1  # pylint: disable=import-outside-toplevel
-    app.register_blueprint(api_healthz, url_prefix='/healthz')
-    app.register_blueprint(api_greeting_v1, url_prefix='/api/greeting/v1')
-    app.register_blueprint(api_greeting_v2, url_prefix='/api/greeting/v2')
-    app.register_blueprint(api_greeting_v3, url_prefix='/api/greeting/v3')
-    app.register_blueprint(api_resource_v1, url_prefix='/api/resource/v1')
+    api.register_blueprint(api_healthz, url_prefix='/healthz')
+    api.register_blueprint(api_greeting_v1, url_prefix='/api/greeting/v1')
+    api.register_blueprint(api_greeting_v2, url_prefix='/api/greeting/v2')
+    api.register_blueprint(api_greeting_v3, url_prefix='/api/greeting/v3')
+    api.register_blueprint(api_resource_v1, url_prefix='/api/resource/v1')
+
+    #
+    # If OAuth2 is in use, register our usage
+
+    api.spec.components.security_scheme('mrmat_keycloak',
+                                        {'type': 'oauth2',
+                                         'description': 'This API uses OAuth 2',
+                                         'flows': {
+                                             'clientCredentials': {
+                                                 'tokenUrl': 'https://keycloak.mrmat.org/auth/realms/master/protocol/openid-connect/token',
+                                                 'scopes': {
+                                                     'mrmat-python-api-flask-resource-read': 'Allows reading objects '
+                                                                                             'in the Resource API',
+                                                     'mrmat-python-api-flask-resource-write': 'Allows creating/modifying'
+                                                                                              ' and deleting objects '
+                                                                                              'in the Resource API'
+                                                 }
+                                             },
+                                             'authorizationCode': {
+                                                 'authorizationUrl': 'https://keycloak.mrmat.org/auth/realms/master/protocol/openid-connect/auth',
+                                                 'tokenUrl': 'https://keycloak.mrmat.org/auth/realms/master/protocol/openid-connect/token',
+                                                 'scopes': {
+                                                     'mrmat-python-api-flask-resource-read': 'Allows reading objects '
+                                                                                             'in the Resource API',
+                                                     'mrmat-python-api-flask-resource-write': 'Allows creating/modifying'
+                                                                                              ' and deleting objects '
+                                                                                              'in the Resource API'
+                                                 }
+                                             }
+                                         }})
 
     return app

.idea/runConfigurations/setup_py__sdist_.xml

@@ -23,4 +23,5 @@
 """Pluggable blueprint of the Greeting API v1
 """
 
+from .model import GreetingV1Output          # noqa: F401
 from .api import bp as api_greeting_v1       # noqa: F401

mrmat_python_api_flask/__init__.py

@@ -22,12 +22,20 @@
 
 """Blueprint for the Greeting API in V1
 """
+from flask.views import MethodView
+from flask_smorest import Blueprint
+from .model import greeting_v1_output, GreetingV1Output
 
-from flask import Blueprint
+bp = Blueprint('greeting_v1',
+               __name__,
+               description='Greeting V1 API')
 
-bp = Blueprint('greeting_v1', __name__)
 
+@bp.route('/')
+class GreetingV1(MethodView):
 
-@bp.route('/', methods=['GET'])
-def get():
-    return {'message': 'Hello World'}, 200
+    @bp.response(200, GreetingV1Output)
+    def get(self):
+        """Get a Hello World message
+        """
+        return greeting_v1_output.dump({'message': 'Hello World'}), 200

mrmat_python_api_flask/apis/greeting/v1/__init__.py

@@ -0,0 +1,43 @@
+#  MIT License
+#
+#  Copyright (c) 2021 MrMat
+#
+#  Permission is hereby granted, free of charge, to any person obtaining a copy
+#  of this software and associated documentation files (the "Software"), to deal
+#  in the Software without restriction, including without limitation the rights
+#  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+#  copies of the Software, and to permit persons to whom the Software is
+#  furnished to do so, subject to the following conditions:
+#
+#  The above copyright notice and this permission notice shall be included in
+#  all copies or substantial portions of the Software.
+#
+#  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+#  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+#  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+#  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+#  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+#  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+#  SOFTWARE.
+
+"""Greeting API v1 Model"""
+
+from marshmallow import fields
+
+from mrmat_python_api_flask import ma
+
+
+class GreetingV1Output(ma.Schema):
+    class Meta:
+        fields = ('message',)
+
+    message = fields.Str(
+        required=True,
+        dump_only=True,
+        metadata={
+            'description': 'The message returned'
+        }
+    )
+
+
+greeting_v1_output = GreetingV1Output()

mrmat_python_api_flask/apis/greeting/v1/api.py

@@ -23,4 +23,5 @@
 """Pluggable blueprint of the Greeting API v2
 """
 
-from .api import bp as api_greeting_v2       # noqa: F401
+from .model import GreetingV2Output, GreetingV2Input          # noqa: F401
+from .api import bp as api_greeting_v2                        # noqa: F401

mrmat_python_api_flask/apis/greeting/v1/model.py

@@ -23,12 +23,31 @@
 """Blueprint for the Greeting API in V2
 """
 
-from flask import Blueprint, request
+from flask.views import MethodView
+from flask_smorest import Blueprint
+from .model import greeting_v2_output, GreetingV2Output, GreetingV2Input
 
-bp = Blueprint('greeting_v2', __name__)
+bp = Blueprint('greeting_v2',
+               __name__,
+               description='Greeting V2 API')
 
 
-@bp.route('/', methods=['GET'])
-def get():
-    name: str = request.args.get('name') or 'World'
-    return {'message': f'Hello {name}'}, 200
+@bp.route('/')
+class GreetingV2(MethodView):
+    """GreetingV2 API Implementation
+    """
+
+    @bp.arguments(GreetingV2Input,
+                  description='The name to greet',
+                  location='query',
+                  required=False,
+                  as_kwargs=True)
+    @bp.response(200, GreetingV2Output)
+    def get(self, **kwargs):
+        """Get a named greeting
+        ---
+        It is possible to place logic here like we do for safe_name, but if we parse
+        the GreetingV2Input via MarshMallow then we can also set a 'default' or 'missing' there.
+        """
+        safe_name: str = kwargs['name'] or 'World'
+        return greeting_v2_output.dump({'message': f'Hello {safe_name}'}), 200

mrmat_python_api_flask/apis/greeting/v2/__init__.py

@@ -0,0 +1,57 @@
+#  MIT License
+#
+#  Copyright (c) 2021 MrMat
+#
+#  Permission is hereby granted, free of charge, to any person obtaining a copy
+#  of this software and associated documentation files (the "Software"), to deal
+#  in the Software without restriction, including without limitation the rights
+#  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+#  copies of the Software, and to permit persons to whom the Software is
+#  furnished to do so, subject to the following conditions:
+#
+#  The above copyright notice and this permission notice shall be included in
+#  all copies or substantial portions of the Software.
+#
+#  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+#  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+#  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+#  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+#  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+#  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+#  SOFTWARE.
+
+"""Greeting API v2 Model"""
+
+from marshmallow import fields
+
+from mrmat_python_api_flask import ma
+
+
+class GreetingV2Input(ma.Schema):
+    class Meta:
+        fields: ('name',)
+
+    name = fields.Str(
+        required=False,
+        load_only=True,
+        missing='Stranger',
+        metadata={
+            'description': 'The name to greet'
+        }
+    )
+
+
+class GreetingV2Output(ma.Schema):
+    class Meta:
+        fields = ('message',)
+
+    message = fields.Str(
+        required=True,
+        dump_only=True,
+        metadata={
+            'description': 'The message returned'
+        }
+    )
+
+
+greeting_v2_output = GreetingV2Output()

mrmat_python_api_flask/apis/greeting/v2/api.py

@@ -23,14 +23,23 @@
 """Blueprint for the Greeting API in V3
 """
 
-from flask import Blueprint, g
-
+from flask import g
+from flask.views import MethodView
+from flask_smorest import Blueprint
 from mrmat_python_api_flask import oidc
+from .model import GreetingV3Output, greeting_v3_output
+
+bp = Blueprint('greeting_v3',
+               __name__,
+               description='The Greeting V3 API')
 
-bp = Blueprint('greeting_v3', __name__)
 
+@bp.route('/')
+class GreetingV3(MethodView):
 
-@bp.route('/', methods=['GET'])
-@oidc.accept_token(require_token=True)
-def get():
-    return {'message': f'Hello {g.oidc_token_info["preferred_username"]}'}, 200
+    @oidc.accept_token(require_token=True)
+    @bp.response(200, GreetingV3Output)
+    def get(self):
+        """Get a greeting for your asserted name from a JWT token
+        """
+        return greeting_v3_output.dump({'message': f'Hello {g.oidc_token_info["preferred_username"]}'}), 200