doc: initial draft for api docs generation

.github/workflows/ci.yaml

@@ -353,3 +353,13 @@ jobs:
         with:
           servicenode-path: ${{ env.PANTOS_SERVICE_NODE }}
           servicenode-version: 'local'
+
+  openapi:
+    name: OpenAPI docs generation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pantos-io/ci-workflows/.github/actions/install-python-deps@v1
+      - name: Build OpenAPI
+        run: |
+          make OPEN_API_OUTPUT=open_api.json docs

Makefile

@@ -19,6 +19,10 @@ check-version:
 		echo "Version check passed" ; \
 	fi
 
+.PHONY: docs
+docs:
+	poetry run python3 -m pantos.servicenode.docs $(OPEN_API_OUTPUT)
+
 .PHONY: dist
 dist: tar wheel debian
 

pantos/servicenode/application.py

@@ -26,6 +26,13 @@
 _logger = logging.getLogger(__name__)
 """Logger for this module."""
 
+def create_dummy_application() -> flask.Flask:
+    """Create a useless dummy web app avoiding all the initialization
+    of additional components. Mainly used for docs generation.
+    
+    """
+    from pantos.servicenode.restapi import flask_app
+    return flask_app
 
 def create_application() -> flask.Flask:
     """Create the service node application.

pantos/servicenode/restapi.py

@@ -289,6 +289,27 @@ class _Bids(flask_restful.Resource):
 
     """
     def get(self) -> flask.Response:
+        """
+        A simple GET endpoint that returns a greeting.
+        ---
+        parameters:
+          - in: query
+            name: source_blockchain
+            schema:
+              $ref: '#/components/schemas/_Bids/properties/source_blockchain' # references the schema which has been added to the definitions in the previous Python code
+            required: true
+            description: Numeric ID of the user to get
+          - in: query
+            name: destination_blockchain
+            schema:
+              $ref: '#/components/schemas/_Bids/properties/destination_blockchain'
+            required: true
+            description: Numeric ID of the user to get
+        responses:
+          200:
+            description: 'ok'
+        """
+
         try:
             query_arguments = flask_restful.request.args
             bids_parameter = _BidsSchema().load(query_arguments)