Extended developer docs. #6

README.md

@@ -22,9 +22,11 @@
         - [Running with Systemd](#running-with-systemd)
         - [Running with Supervisor](#running-with-supervisor)
         - [Running with Docker](#running-with-docker)
-            - [Creating a local image (Developers)](#creating-a-local-image-developers)
-            - [Publish new image (Developers)](#publish-new-image-developers)
-    - [Using the API (Developers)](#using-the-api-developers)
+    - [Development](#development-1)
+        - [Using the API](#using-the-api)
+        - [Extending the API](#extending-the-api)
+        - [Creating a local image](#creating-a-local-image)
+        - [Publish new image](#publish-new-image)
 - [About](#about)
 
 <!-- /TOC -->
@@ -290,25 +292,9 @@ The project also contains a convenience script to get started with a one-liner
 ./run.sh docker:api
 ```
 
-#### Creating a local image (Developers)
+## Development
 
-If you are a developer and want to create a local image, run
-
-```bash
-# Build the image
-./run.sh docker:build
-```
-
-#### Publish new image (Developers)
-
-If  you are developer and want to publish a new image to DockerHub, run
-
-```bash
-# Releasing the image to DockerHub
-./run.sh docker:push
-```
-
-## Using the API (Developers)
+### Using the API
 
 You can find details on the available API endpoints here: https://app.swaggerhub.com/apis/AURA-Engine/engine-api/1.0.0
 
@@ -341,6 +327,36 @@ Your OpenAPI definition lives here:
 http://localhost:8008/api/v1/openapi.json
 ```
 
+### Extending the API
+
+The workflow for extending the API follows the **API First** approach. This means you have to edit the API at https://app.swaggerhub.com/apis/AURA-Engine/engine-api/,
+then download the `python-flask` server stubs, and replace & merge the existing generated sources in `./src/rest`.
+
+All model files can usually be overwritten. Only controller and test classes need to undergo a merge action.
+
+In the future it might be favorable to use a local Codegen to generate the API artifacts.
+
+> Caveat: There is an issue with the generated source related to Python 3.7. Therefore `./src/rest/util.py` contains a workaround. Think about that when
+overwriting the existing file.
+
+### Creating a local image
+
+If you are a developer and want to create a local image, run
+
+```bash
+# Build the image
+./run.sh docker:build
+```
+
+### Publish new image
+
+If  you are developer and want to publish a new image to DockerHub, run
+
+```bash
+# Releasing the image to DockerHub
+./run.sh docker:push
+```
+
 # About
 
 Aura Engine API is the API interface for the play-out engine of the [Aura Radio Software Suite](https://gitlab.servus.at/aura/meta).