diff --git a/src/main/resources/api-definition.yaml b/src/main/resources/api-definition.yaml
index 09c2ffe8..00477766 100644
--- a/src/main/resources/api-definition.yaml
+++ b/src/main/resources/api-definition.yaml
@@ -8,144 +8,29 @@ servers:
 
 paths:
 
-    /api/customers:
-        get:
-            summary: Returns a list of (optionally filtered) customers.
-            description: Returns the list of (optionally filtered) customers which are visible to the current user or any of it's assumed roles.
-            tags:
-                - customers
-            operationId: listCustomers
-            parameters:
-                - $ref: '#/components/parameters/currentUser'
-                - $ref: '#/components/parameters/assumedRoles'
-                - name: prefix
-                  in: query
-                  required: false
-                  schema:
-                      type: string
-                  description: Customer-prefix to filter the results.
-            responses:
-                "200":
-                    description: OK
-                    content:
-                        'application/json':
-                            schema:
-                                type: array
-                                items:
-                                    $ref: '#/components/schemas/Customer'
-                "401":
-                    description: Not Authorized
-                "403":
-                    description: Forbidden
-        post:
-            summary: Adds a new customer.
-            tags:
-                - customers
-            operationId: addCustomer
-            parameters:
-                - $ref: '#/components/parameters/currentUser'
-                - $ref: '#/components/parameters/assumedRoles'
-            requestBody:
-                content:
-                    'application/json':
-                        schema:
-                            $ref: '#/components/schemas/Customer'
-                required: true
-            responses:
-                "200":
-                    description: OK
-                    content:
-                        'application/json':
-                            schema:
-                                $ref: '#/components/schemas/Customer'
+    # RBAC
 
     /api/rbac-users:
-        get:
-            tags:
-                - rbacusers
-            description: List accessible RBAC users with optional filter by name.
-            operationId: listUsers
-            parameters:
-                - $ref: '#/components/parameters/currentUser'
-                - $ref: '#/components/parameters/assumedRoles'
-                - name: name
-                  in: query
-                  required: false
-                  schema:
-                      type: string
-            responses:
-                "200":
-                    description: OK
-                    content:
-                        'application/json':
-                            schema:
-                                type: array
-                                items:
-                                    $ref: '#/components/schemas/RbacUser'
-                "401":
-                    description: if the 'current-user' cannot be identified
-                    content:
-                        'application/json':
-                            schema:
-                                type: array
-                                items:
-                                    $ref: '#/components/schemas/RbacUser'
-                "403":
-                    description: if the 'current-user' is not allowed to assume any of the roles
-                        from 'assumed-roles'
-                    content:
-                        'application/json':
-                            schema:
-                                type: array
-                                items:
-                                    $ref: '#/components/schemas/RbacUser'
+        $ref: "./api-definition/rbac-users.yaml"
 
     /api/rbac-users/{userName}/permissions:
-        get:
-            tags:
-                - rbacusers
-            description: 'List all visible permissions granted to the given user; reduced '
-            operationId: listUserPermissions
-            parameters:
-                - $ref: '#/components/parameters/currentUser'
-                - $ref: '#/components/parameters/assumedRoles'
-                - name: userName
-                  in: path
-                  required: true
-                  schema:
-                      type: string
-            responses:
-                "200":
-                    description: OK
-                    content:
-                        'application/json':
-                            schema:
-                                type: array
-                                items:
-                                    $ref: '#/components/schemas/RbacUserPermission'
-
-                "401":
-                    $ref: '#/components/responses/Unauthorized'
-                "403":
-                    $ref: '#/components/responses/Forbidden'
+        $ref: "./api-definition/rbac-users-permissions.yaml"
 
     /api/rbac-roles:
-        get:
-            tags:
-                - rbacroles
-            operationId: listRoles
-            parameters:
-                - $ref: '#/components/parameters/currentUser'
-                - $ref: '#/components/parameters/assumedRoles'
-            responses:
-                "200":
-                    description: OK
-                    content:
-                        'application/json':
-                            schema:
-                                type: array
-                                items:
-                                    $ref: '#/components/schemas/RbacRole'
+        $ref: "./api-definition/rbac-roles.yaml"
+
+    # HS
+
+    /api/customers:
+        $ref: "./api-definition/hs-customers.yaml"
+
+    /api/packages:
+        $ref: "./api-definition/hs-packages.yaml"
+
+    /api/packages/{packageUUID}:
+        $ref: "./api-definition/hs-packages-uuid.yaml"
+
+    # Other
 
     /api/ping:
         get:
@@ -159,192 +44,3 @@ paths:
                         'application/json':
                             schema:
                                 type: string
-
-    /api/packages:
-        get:
-            tags:
-                - packages
-            operationId: listPackages
-            parameters:
-                - $ref: '#/components/parameters/currentUser'
-                - $ref: '#/components/parameters/assumedRoles'
-                - name: name
-                  in: query
-                  required: false
-                  schema:
-                      type: string
-            responses:
-                "200":
-                    description: OK
-                    content:
-                        'application/json':
-                            schema:
-                                type: array
-                                items:
-                                    $ref: '#/components/schemas/Package'
-                "401":
-                    $ref: '#/components/responses/Unauthorized'
-                "403":
-                    $ref: '#/components/responses/Forbidden'
-    /api/packages/{packageUUID}:
-        patch:
-            tags:
-                - packages
-            operationId: updatePackage
-            parameters:
-                -   $ref: '#/components/parameters/currentUser'
-                -   $ref: '#/components/parameters/assumedRoles'
-                -   name: packageUUID
-                    in: path
-                    required: true
-                    schema:
-                        type: string
-                        format: uuid
-            requestBody:
-                content:
-                    'application/json':
-                        schema:
-                            $ref: '#/components/schemas/PackageUpdate'
-            responses:
-                "200":
-                    description: OK
-                    content:
-                        'application/json':
-                            schema:
-                                $ref: '#/components/schemas/Package'
-                "401":
-                    $ref: '#/components/responses/Unauthorized'
-                "403":
-                    $ref: '#/components/responses/Forbidden'
-
-components:
-
-    parameters:
-        currentUser:
-            name: current-user
-            in: header
-            required: true
-            schema:
-                type: string
-            description: Identifying name of the currently logged in user.
-        assumedRoles:
-            name: assumed-roles
-            in: header
-            required: false
-            schema:
-                type: string
-            description: Semicolon-separated list of roles to assume. The current user needs to have the right to assume these roles.
-
-    responses:
-        NotFound:
-            description: The specified  was not found.
-            content:
-                application/json:
-                    schema:
-                        $ref: '#/components/schemas/Error'
-        Unauthorized:
-            description: The current user is unknown or not authorized.
-            content:
-                application/json:
-                    schema:
-                        $ref: '#/components/schemas/Error'
-        Forbidden:
-            description: The current user or none of the assumed or roles is granted access to the .
-            content:
-                application/json:
-                    schema:
-                        $ref: '#/components/schemas/Error'
-
-    schemas:
-        Customer:
-            type: object
-            properties:
-                uuid:
-                    type: string
-                    format: uuid
-                prefix:
-                    type: string
-                reference:
-                    type: integer
-                    format: int32
-                adminUserName:
-                    type: string
-        RbacUser:
-            type: object
-            properties:
-                uuid:
-                    type: string
-                    format: uuid
-                name:
-                    type: string
-        RbacUserPermission:
-            type: object
-            properties:
-                objectUuid:
-                    type: string
-                    format: uuid
-                objectTable:
-                    type: string
-                objectIdName:
-                    type: string
-                roleName:
-                    type: string
-                roleUuid:
-                    type: string
-                    format: uuid
-                permissionUuid:
-                    type: string
-                    format: uuid
-                op:
-                    type: string
-        RbacRole:
-            type: object
-            properties:
-                uuid:
-                    type: string
-                    format: uuid
-                objectUuid:
-                    type: string
-                    format: uuid
-                objectTable:
-                    type: string
-                objectIdName:
-                    type: string
-                roleType:
-                    type: string
-                    enum:
-                        - owner
-                        - admin
-                        - tenant
-                roleName:
-                    type: string
-        Package:
-            type: object
-            properties:
-                uuid:
-                    type: string
-                    format: uuid
-                customer:
-                    $ref: '#/components/schemas/Customer'
-                name:
-                    type: string
-                description:
-                    type: string
-                    maxLength: 80
-        PackageUpdate:
-            type: object
-            properties:
-                description:
-                    type: string
-                    maxLength: 80
-                    nullable: true
-        Error:
-            type: object
-            properties:
-                code:
-                    type: string
-                message:
-                    type: string
-            required:
-                - code
-                - message
diff --git a/src/main/resources/api-definition/README.md b/src/main/resources/api-definition/README.md
new file mode 100644
index 00000000..d26352cb
--- /dev/null
+++ b/src/main/resources/api-definition/README.md
@@ -0,0 +1,5 @@
+The symbolik self-link 'api-definition' is a workaround to align IntelliJ IDEAs relative link interpretation with the interpretation of OpenAPI-generator.
+Where IDEA only uses the path of the file in which the `$ref` is used,
+the OpenAPI-generator always uses the path of the root API definition to resolve relative links.
+
+See also https://github.com/OpenAPITools/openapi-generator/issues/10320.
diff --git a/src/main/resources/api-definition/api-definition b/src/main/resources/api-definition/api-definition
new file mode 120000
index 00000000..945c9b46
--- /dev/null
+++ b/src/main/resources/api-definition/api-definition
@@ -0,0 +1 @@
+.
\ No newline at end of file
diff --git a/src/main/resources/api-definition/auth.yaml b/src/main/resources/api-definition/auth.yaml
new file mode 100644
index 00000000..65d491fb
--- /dev/null
+++ b/src/main/resources/api-definition/auth.yaml
@@ -0,0 +1,20 @@
+
+components:
+
+    parameters:
+
+        currentUser:
+            name: current-user
+            in: header
+            required: true
+            schema:
+                type: string
+            description: Identifying name of the currently logged in user.
+
+        assumedRoles:
+            name: assumed-roles
+            in: header
+            required: false
+            schema:
+                type: string
+            description: Semicolon-separated list of roles to assume. The current user needs to have the right to assume these roles.
diff --git a/src/main/resources/api-definition/error-responses.yaml b/src/main/resources/api-definition/error-responses.yaml
new file mode 100644
index 00000000..8d080237
--- /dev/null
+++ b/src/main/resources/api-definition/error-responses.yaml
@@ -0,0 +1,34 @@
+components:
+
+    responses:
+        NotFound:
+            description: The specified  was not found.
+            content:
+                application/json:
+                    schema:
+                        $ref: '#/components/schemas/Error'
+        Unauthorized:
+            description: The current user is unknown or not authorized.
+            content:
+                application/json:
+                    schema:
+                        $ref: '#/components/schemas/Error'
+        Forbidden:
+            description: The current user or none of the assumed or roles is granted access to the .
+            content:
+                application/json:
+                    schema:
+                        $ref: '#/components/schemas/Error'
+
+    schemas:
+
+        Error:
+            type: object
+            properties:
+                code:
+                    type: string
+                message:
+                    type: string
+            required:
+                - code
+                - message
diff --git a/src/main/resources/api-definition/hs-customer-schemas.yaml b/src/main/resources/api-definition/hs-customer-schemas.yaml
new file mode 100644
index 00000000..63d662bf
--- /dev/null
+++ b/src/main/resources/api-definition/hs-customer-schemas.yaml
@@ -0,0 +1,19 @@
+
+components:
+
+    schemas:
+
+        Customer:
+            type: object
+            properties:
+                uuid:
+                    type: string
+                    format: uuid
+                prefix:
+                    type: string
+                reference:
+                    type: integer
+                    format: int32
+                adminUserName:
+                    type: string
+
diff --git a/src/main/resources/api-definition/hs-customers.yaml b/src/main/resources/api-definition/hs-customers.yaml
new file mode 100644
index 00000000..d57022b0
--- /dev/null
+++ b/src/main/resources/api-definition/hs-customers.yaml
@@ -0,0 +1,54 @@
+get:
+    summary: Returns a list of (optionally filtered) customers.
+    description: Returns the list of (optionally filtered) customers which are visible to the current user or any of it's assumed roles.
+    tags:
+        - customers
+    operationId: listCustomers
+    parameters:
+        - $ref: './api-definition/auth.yaml#/components/parameters/currentUser'
+        - $ref: './api-definition/auth.yaml#/components/parameters/assumedRoles'
+        - name: prefix
+          in: query
+          required: false
+          schema:
+              type: string
+          description: Customer-prefix to filter the results.
+    responses:
+        "200":
+            description: OK
+            content:
+                'application/json':
+                    schema:
+                        type: array
+                        items:
+                            $ref: './api-definition/hs-customer-schemas.yaml#/components/schemas/Customer'
+        "401":
+            $ref: './api-definition/error-responses.yaml#/components/responses/Unauthorized'
+        "403":
+            $ref: './api-definition/error-responses.yaml#/components/responses/Forbidden'
+
+post:
+    summary: Adds a new customer.
+    tags:
+        - customers
+    operationId: addCustomer
+    parameters:
+        - $ref: './api-definition/auth.yaml#/components/parameters/currentUser'
+        - $ref: './api-definition/auth.yaml#/components/parameters/assumedRoles'
+    requestBody:
+        content:
+            'application/json':
+                schema:
+                    $ref: './api-definition/api-definition/hs-customer-schemas.yaml#/components/schemas/Customer'
+        required: true
+    responses:
+        "200":
+            description: OK
+            content:
+                'application/json':
+                    schema:
+                        $ref: './api-definition/hs-customer-schemas/components.yaml#/schemas/Customer'
+        "401":
+            $ref: './api-definition/error-responses.yaml#/components/responses/Unauthorized'
+        "403":
+            $ref: './api-definition/error-responses.yaml#/components/responses/Forbidden'
diff --git a/src/main/resources/api-definition/hs-package-schemas.yaml b/src/main/resources/api-definition/hs-package-schemas.yaml
new file mode 100644
index 00000000..201e518e
--- /dev/null
+++ b/src/main/resources/api-definition/hs-package-schemas.yaml
@@ -0,0 +1,25 @@
+
+components:
+
+    schemas:
+
+        Package:
+            type: object
+            properties:
+                uuid:
+                    type: string
+                    format: uuid
+                customer:
+                    $ref: './api-definition/hs-customers-schemas.yaml#/components/schemas/Customer'
+                name:
+                    type: string
+                description:
+                    type: string
+                    maxLength: 80
+        PackageUpdate:
+            type: object
+            properties:
+                description:
+                    type: string
+                    maxLength: 80
+                    nullable: true
diff --git a/src/main/resources/api-definition/hs-packages-uuid.yaml b/src/main/resources/api-definition/hs-packages-uuid.yaml
new file mode 100644
index 00000000..864e816a
--- /dev/null
+++ b/src/main/resources/api-definition/hs-packages-uuid.yaml
@@ -0,0 +1,29 @@
+patch:
+    tags:
+        - packages
+    operationId: updatePackage
+    parameters:
+        -   $ref: '#/components/parameters/currentUser'
+        -   $ref: '#/components/parameters/assumedRoles'
+        -   name: packageUUID
+            in: path
+            required: true
+            schema:
+                type: string
+                format: uuid
+    requestBody:
+        content:
+            'application/json':
+                schema:
+                    $ref: '#/components/schemas/PackageUpdate'
+    responses:
+        "200":
+            description: OK
+            content:
+                'application/json':
+                    schema:
+                        $ref: '#/components/schemas/Package'
+        "401":
+            $ref: '#/components/responses/Unauthorized'
+        "403":
+            $ref: '#/components/responses/Forbidden'
diff --git a/src/main/resources/api-definition/hs-packages.yaml b/src/main/resources/api-definition/hs-packages.yaml
new file mode 100644
index 00000000..705af1b1
--- /dev/null
+++ b/src/main/resources/api-definition/hs-packages.yaml
@@ -0,0 +1,25 @@
+get:
+    tags:
+        - packages
+    operationId: listPackages
+    parameters:
+        - $ref: './auth.yaml#/components/parameters/currentUser'
+        - $ref: './auth.yaml#/components/parameters/assumedRoles'
+        - name: name
+          in: query
+          required: false
+          schema:
+              type: string
+    responses:
+        "200":
+            description: OK
+            content:
+                'application/json':
+                    schema:
+                        type: array
+                        items:
+                            $ref: './hs-package-schemas/components/schemas/Package'
+        "401":
+            $ref: './error-responses.yaml#/components/responses/Unauthorized'
+        "403":
+            $ref: './error-responses.yaml#/components/responses/Forbidden'
diff --git a/src/main/resources/api-definition/rbac-role-schemas.yaml b/src/main/resources/api-definition/rbac-role-schemas.yaml
new file mode 100644
index 00000000..589c00b8
--- /dev/null
+++ b/src/main/resources/api-definition/rbac-role-schemas.yaml
@@ -0,0 +1,26 @@
+
+components:
+
+    schemas:
+
+        RbacRole:
+            type: object
+            properties:
+                uuid:
+                    type: string
+                    format: uuid
+                objectUuid:
+                    type: string
+                    format: uuid
+                objectTable:
+                    type: string
+                objectIdName:
+                    type: string
+                roleType:
+                    type: string
+                    enum:
+                        - owner
+                        - admin
+                        - tenant
+                roleName:
+                    type: string
diff --git a/src/main/resources/api-definition/rbac-roles.yaml b/src/main/resources/api-definition/rbac-roles.yaml
new file mode 100644
index 00000000..9831628a
--- /dev/null
+++ b/src/main/resources/api-definition/rbac-roles.yaml
@@ -0,0 +1,16 @@
+get:
+    tags:
+        - rbacroles
+    operationId: listRoles
+    parameters:
+        - $ref: './api-definition/auth.yaml#/components/parameters/currentUser'
+        - $ref: './api-definition/auth.yaml#/components/parameters/assumedRoles'
+    responses:
+        "200":
+            description: OK
+            content:
+                'application/json':
+                    schema:
+                        type: array
+                        items:
+                            $ref: './api-definition/rbac-role-schemas.yaml#/components/schemas/RbacRole'
diff --git a/src/main/resources/api-definition/rbac-user-schemas.yaml b/src/main/resources/api-definition/rbac-user-schemas.yaml
new file mode 100644
index 00000000..c7ca49c0
--- /dev/null
+++ b/src/main/resources/api-definition/rbac-user-schemas.yaml
@@ -0,0 +1,33 @@
+
+components:
+
+    schemas:
+
+        RbacUser:
+            type: object
+            properties:
+                uuid:
+                    type: string
+                    format: uuid
+                name:
+                    type: string
+        RbacUserPermission:
+            type: object
+            properties:
+                objectUuid:
+                    type: string
+                    format: uuid
+                objectTable:
+                    type: string
+                objectIdName:
+                    type: string
+                roleName:
+                    type: string
+                roleUuid:
+                    type: string
+                    format: uuid
+                permissionUuid:
+                    type: string
+                    format: uuid
+                op:
+                    type: string
diff --git a/src/main/resources/api-definition/rbac-users-permissions.yaml b/src/main/resources/api-definition/rbac-users-permissions.yaml
new file mode 100644
index 00000000..8ac92372
--- /dev/null
+++ b/src/main/resources/api-definition/rbac-users-permissions.yaml
@@ -0,0 +1,27 @@
+get:
+    tags:
+        - rbacusers
+    description: 'List all visible permissions granted to the given user; reduced '
+    operationId: listUserPermissions
+    parameters:
+        - $ref: './api-definition/auth.yaml#/components/parameters/currentUser'
+        - $ref: './api-definition/auth.yaml#/components/parameters/assumedRoles'
+        - name: userName
+          in: path
+          required: true
+          schema:
+              type: string
+    responses:
+        "200":
+            description: OK
+            content:
+                'application/json':
+                    schema:
+                        type: array
+                        items:
+                            $ref: './api-definition/rbac-user-schemas.yaml#/components/schemas/RbacUserPermission'
+
+        "401":
+            $ref: './api-definition/error-responses.yaml#/components/responses/Unauthorized'
+        "403":
+            $ref: './api-definition/error-responses.yaml#/components/responses/Forbidden'
diff --git a/src/main/resources/api-definition/rbac-users.yaml b/src/main/resources/api-definition/rbac-users.yaml
new file mode 100644
index 00000000..f8c23289
--- /dev/null
+++ b/src/main/resources/api-definition/rbac-users.yaml
@@ -0,0 +1,39 @@
+get:
+    tags:
+        - rbacusers
+    description: List accessible RBAC users with optional filter by name.
+    operationId: listUsers
+    parameters:
+        - $ref: './api-definition/auth.yaml#/components/parameters/currentUser'
+        - $ref: './api-definition/auth.yaml#/components/parameters/assumedRoles'
+        - name: name
+          in: query
+          required: false
+          schema:
+              type: string
+    responses:
+        "200":
+            description: OK
+            content:
+                'application/json':
+                    schema:
+                        type: array
+                        items:
+                            $ref: './api-definition/rbac-user-schemas.yaml#/components/schemas/RbacUser'
+        "401":
+            description: if the 'current-user' cannot be identified
+            content:
+                'application/json':
+                    schema:
+                        type: array
+                        items:
+                            $ref: './api-definition/rbac-user-schemas.yaml#/components/schemas/RbacUser'
+        "403":
+            description: if the 'current-user' is not allowed to assume any of the roles
+                from 'assumed-roles'
+            content:
+                'application/json':
+                    schema:
+                        type: array
+                        items:
+                            $ref: './api-definition/rbac-user-schemas.yaml#/components/schemas/RbacUser'