Added specification for API.

api.py

@@ -32,6 +32,9 @@ from flask                          import Flask
 from flask_sqlalchemy               import SQLAlchemy
 from flask_marshmallow              import Marshmallow
 from flask_restful                  import Api, Resource
+from apispec                        import APISpec
+from apispec.ext.marshmallow        import MarshmallowPlugin
+from apispec_webframeworks.flask    import FlaskPlugin
 
 from libraries.base.logger          import AuraLogger
 from libraries.base.config          import AuraConfig
@@ -77,6 +80,8 @@ class EngineApi:
         self.logger = logging.getLogger("engine-api")
         self.api = api
 
+        spec.components.schema("TrackService", schema=TrackServiceSchema)
+        
         # Schema instances
         EngineApi.trackservice_schema = TrackServiceSchema(many=True)
         EngineApi.track_schema = TrackServiceSchema()
@@ -90,6 +95,10 @@ class EngineApi:
 
         self.logger.info("Engine API routes successfully set!")
 
+        # Print the API Spec
+        # TODO Generates HTML for specification
+        # self.logger.info(spec.to_dict())
+        # self.logger.info(spec.to_yaml())
 
     def run(self):
         """
@@ -103,12 +112,35 @@ class EngineApi:
 
 
 
+#
+# API SPEC
+#
+
+
+spec = APISpec(
+    title="Swagger API Specification for Aura Engine",
+    version="1.0.0",
+    openapi_version="3.0.2",
+    plugins=[FlaskPlugin(), MarshmallowPlugin()],
+)
+
+
 #
 # API SCHEMA
 #
 
 
 class TrackServiceSchema(ma.Schema):
+    """A cute furry animal endpoint.
+    ---
+    get:
+      description: Get a random pet
+      responses:
+        200:
+          content:
+            application/json:
+              schema: PetSchema
+    """
     class Meta:
         fields = ("id", "schedule_start", "track_start", "fallback", "artist", "title", "album", "duration")
 
@@ -173,5 +205,5 @@ class TracksByDayResource(Resource):
 if __name__ == "__main__":
     engine_api = EngineApi(config, api)
     engine_api.run()
-
+    
     
\ No newline at end of file

docs/engine-features.md

@@ -59,4 +59,27 @@ The Track Service API provides following endpoints:
 * `/api/v1/current` ...... Returns the currently playing track
 * `/api/v1/day/$DAY` ..... Returns the tracks for a given day formated as `YYYY-MM-DD`
 
+The Swagger Specification of a Track Service entry as YAML looks like this:
+
+```yaml
+    components:
+    schemas:
+        TrackService:
+        properties:
+            album: {}
+            artist: {}
+            duration: {}
+            fallback: {}
+            id: {}
+            schedule_start: {}
+            title: {}
+            track_start: {}
+        type: object
+    info:
+    title: Swagger API Specification for Aura Engine
+    version: 1.0.0
+    openapi: 3.0.2
+    paths: {}
+```
+
 # Programme API
\ No newline at end of file

requirements.txt

@@ -4,6 +4,8 @@ Flask-SQLAlchemy==2.4.1
 Flask-RESTful==0.3.8
 flask-marshmallow==0.11.0
 marshmallow-sqlalchemy==0.22.2
+apispec==3.3.0
+apispec-webframeworks==0.5.2
 mysqlclient==1.3.12
 redis==3.4.1
 mutagen==1.44.0