master > master: code py - schemata überarbeitet

code/python/justfile

@@ -12,6 +12,7 @@ _default:
 
 PYTHON := if os_family() == "windows" { "py -3" } else { "python3" }
 GEN_MODELS := "datamodel-codegen"
+GEN_MODELS_DOCUMENTATION := "openapi-generator"
 
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 # Macros
@@ -56,6 +57,16 @@ _generate-models path name:
         --input {{path}}/{{name}}-schema.yaml \
         --output {{path}}/generated/{{name}}.py
 
+_generate-models-documentation path name:
+    @- just _delete-if-folder-exists "docs/{{name}}"
+    @- just _create-folder-if-not-exists "docs/{{name}}"
+    @- {{GEN_MODELS_DOCUMENTATION}} generate \
+        --input-spec {{path}}/{{name}}-schema.yaml \
+        --generator-name markdown \
+        --output "docs/{{name}}"
+    @- just _clean-all-files .openapi-generator*
+    @- just _clean-all-folders .openapi-generator*
+
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 # TARGETS
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -68,12 +79,23 @@ build: _build-requirements _build-skip-requirements
 _build-skip-requirements: build-models
 _build-requirements:
     @{{PYTHON}} -m pip install --disable-pip-version-check -r requirements.txt
-build-models: _check-system-requirements _build-models-nochecks
-_build-models-nochecks:
+build-models:
+    @just _check-system-requirements
+    @just _build-models
+    @just _build-models-documentation
+_build-models:
     @echo "Generate data models from schemata."
+    @just _delete-if-folder-exists "models/generated"
     @just _create-folder-if-not-exists "models/generated"
     @- just _generate-models "models" "config"
     @- just _generate-models "models" "commands"
+_build-models-documentation:
+    @echo "Generate documentations data models from schemata."
+    @just _delete-if-folder-exists "docs"
+    @just _create-folder-if-not-exists "docs"
+    @- just _generate-models-documentation "models" "config"
+    @- just _generate-models-documentation "models" "commands"
+
 
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 # TARGETS: run
@@ -172,3 +194,7 @@ _check-system-requirements:
         echo "Command '{{GEN_MODELS}}' did not work. Ensure that the installation of 'datamodel-code-generator' worked and that system paths are set." \
         exit 1; \
     fi
+    @if ! ( {{GEN_MODELS_DOCUMENTATION}} --help >> /dev/null 2> /dev/null ); then \
+        echo "Command '{{GEN_MODELS_DOCUMENTATION}}' did not work. Ensure that the installation of 'datamodel-code-generator' worked and that system paths are set." \
+        exit 1; \
+    fi

code/python/models/commands-schema.yaml

@@ -2,7 +2,8 @@ openapi: 3.0.3
 info:
   version: 0.1.0
   title: Schemata for command instructions
-servers: []
+servers:
+  - url: "."
 paths: {}
 components:
   schemas:
@@ -22,9 +23,10 @@ components:
     Command:
       description: |-
         Instructions for command to call
+      type: object
       required:
         - name
-      properties: &ref_command_properties
+      properties:
         name:
           $ref: '#/components/schemas/EnumAlgorithmNames'
       additionalProperties: true
@@ -40,16 +42,26 @@ components:
         - nodes
         - edges
       properties:
-        <<: *ref_command_properties
+        name:
+          $ref: '#/components/schemas/EnumAlgorithmNames'
         nodes:
           type: array
+          items:
+            anyOf:
+              - type: integer
+              - type: number
+              - type: string
         edges:
           type: array
           items:
-            # $ref: '#/components/schemas/Edge'
             type: array
             minItems: 2
             maxItems: 2
+            items:
+              anyOf:
+                - type: integer
+                - type: number
+                - type: string
     # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     # Command - Algorithm: TSP
     # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -62,7 +74,8 @@ components:
         - optimise
         - dist
       properties:
-        <<: *ref_command_properties
+        name:
+          $ref: '#/components/schemas/EnumAlgorithmNames'
         dist:
           type: array
           items:
@@ -83,7 +96,8 @@ components:
         - word1
         - word2
       properties:
-        <<: *ref_command_properties
+        name:
+          $ref: '#/components/schemas/EnumAlgorithmNames'
         word1:
           description: Word that gets placed vertically in algorithm.
           type: string

code/python/models/config-schema.yaml

@@ -2,7 +2,8 @@ openapi: 3.0.3
 info:
   version: 0.1.0
   title: Schemata for config models
-servers: []
+servers:
+  - url: "."
 paths: {}
 components:
   schemas:
@@ -10,7 +11,7 @@ components:
     # Config
     # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     Config:
-      descripton: |-
+      description: |-
         Data model for all parts of the configuration.
       type: object
       required:

code/python/requirements.txt

@@ -23,6 +23,7 @@ lazy-load>=0.8.2
 pyyaml>=6.0
 pydantic>=1.9.0
 datamodel-code-generator>=0.13.0
+openapi-generator-cli>=4.3.1
 
 # misc
 lorem>=0.1.1