HYPERFLEET-1024 fix: resolve spectral warnings, set to fail on warnings

Author: mliptak0

.github/workflows/ci.yml

@@ -41,7 +41,7 @@ jobs:
 
       - name: Lint OpenAPI schemas
         run: |
-          node_modules/.bin/spectral lint schemas/core/openapi.yaml schemas/gcp/openapi.yaml --format github-actions
+          npx spectral lint schemas/core/openapi.yaml schemas/gcp/openapi.yaml --format github-actions --fail-severity warn
 
       - name: Check version bump
         env:

.spectral.yaml

@@ -1 +1,7 @@
 extends: ["spectral:oas"]
+overrides:
+  - files:
+      - "schemas/core/openapi.yaml#/components/schemas/BearerAuth"
+      - "schemas/gcp/openapi.yaml#/components/schemas/BearerAuth"
+    rules:
+      oas3-unused-component: off

schemas/core/openapi.yaml

@@ -13,12 +13,17 @@ info:
     **Architecture**: Simple CRUD only, no business logic, no event creation.
     Sentinel operator handles all orchestration logic.
     Adapters handle the specifics of managing spec
-tags: []
+tags:
+  - name: Clusters
+  - name: Cluster statuses
+  - name: NodePool statuses
+  - name: NodePools
 paths:
   /api/hyperfleet/v1/clusters:
     get:
       operationId: getClusters
       summary: List clusters
+      description: Returns a list of all clusters.
       parameters:
         - $ref: '#/components/parameters/SearchParams'
         - $ref: '#/components/parameters/QueryParams.page'
@@ -40,6 +45,8 @@ paths:
             application/problem+json:
               schema:
                 $ref: '#/components/schemas/Error'
+      tags:
+        - Clusters
       security:
         - BearerAuth: []
     post:
@@ -67,6 +74,8 @@ paths:
             application/problem+json:
               schema:
                 $ref: '#/components/schemas/Error'
+      tags:
+        - Clusters
       requestBody:
         required: true
         content:
@@ -79,6 +88,7 @@ paths:
     get:
       operationId: getClusterById
       summary: Get cluster by ID
+      description: Returns a single cluster by its ID.
       parameters:
         - $ref: '#/components/parameters/SearchParams'
         - name: cluster_id
@@ -101,6 +111,8 @@ paths:
             application/problem+json:
               schema:
                 $ref: '#/components/schemas/Error'
+      tags:
+        - Clusters
       security:
         - BearerAuth: []
     patch:
@@ -133,6 +145,8 @@ paths:
             application/problem+json:
               schema:
                 $ref: '#/components/schemas/Error'
+      tags:
+        - Clusters
       requestBody:
         required: true
         content:
@@ -229,6 +243,8 @@ paths:
             application/problem+json:
               schema:
                 $ref: '#/components/schemas/Error'
+      tags:
+        - Clusters
       security:
         - BearerAuth: []
   /api/hyperfleet/v1/clusters/{cluster_id}/nodepools:
@@ -263,6 +279,8 @@ paths:
             application/problem+json:
               schema:
                 $ref: '#/components/schemas/Error'
+      tags:
+        - NodePools
       security:
         - BearerAuth: []
     post:
@@ -293,6 +311,8 @@ paths:
             application/problem+json:
               schema:
                 $ref: '#/components/schemas/Error'
+      tags:
+        - NodePools
       requestBody:
         required: true
         content:
@@ -334,6 +354,8 @@ paths:
             application/problem+json:
               schema:
                 $ref: '#/components/schemas/Error'
+      tags:
+        - NodePools
       security:
         - BearerAuth: []
     delete:
@@ -434,6 +456,8 @@ paths:
             application/problem+json:
               schema:
                 $ref: '#/components/schemas/Error'
+      tags:
+        - NodePools
       security:
         - BearerAuth: []
     patch:
@@ -472,6 +496,8 @@ paths:
             application/problem+json:
               schema:
                 $ref: '#/components/schemas/Error'
+      tags:
+        - NodePools
       requestBody:
         required: true
         content:
@@ -516,6 +542,8 @@ paths:
           description: The server cannot find the requested resource.
         '409':
           description: The request conflicts with the current state of the server.
+      tags:
+        - NodePool statuses
       requestBody:
         required: true
         content:
@@ -527,6 +555,7 @@ paths:
     put:
       operationId: putNodePoolStatuses
       summary: Adapter creates or updates resource nodepool status
+      description: Idempotent upsert of an adapter status for this nodepool. Use instead of POST when the adapter name is known upfront.
       parameters:
         - name: cluster_id
           in: path
@@ -553,6 +582,8 @@ paths:
           description: The server cannot find the requested resource.
         '409':
           description: The request conflicts with the current state of the server.
+      tags:
+        - NodePool statuses
       requestBody:
         required: true
         content:
@@ -597,6 +628,8 @@ paths:
             application/problem+json:
               schema:
                 $ref: '#/components/schemas/Error'
+      tags:
+        - NodePool statuses
   /api/hyperfleet/v1/clusters/{cluster_id}/statuses:
     post:
       operationId: postClusterStatuses
@@ -627,6 +660,8 @@ paths:
           description: The server cannot find the requested resource.
         '409':
           description: The request conflicts with the current state of the server.
+      tags:
+        - Cluster statuses
       requestBody:
         required: true
         content:
@@ -638,6 +673,7 @@ paths:
     put:
       operationId: putClusterStatuses
       summary: Adapter creates or updates resource cluster status
+      description: Idempotent upsert of an adapter status for this cluster. Use instead of POST when the adapter name is known upfront.
       parameters:
         - name: cluster_id
           in: path
@@ -658,6 +694,8 @@ paths:
           description: The server cannot find the requested resource.
         '409':
           description: The request conflicts with the current state of the server.
+      tags:
+        - Cluster statuses
       requestBody:
         required: true
         content:
@@ -693,6 +731,8 @@ paths:
           description: The server could not understand the request due to invalid syntax.
         '404':
           description: The server cannot find the requested resource.
+      tags:
+        - Cluster statuses
       security:
         - BearerAuth: []
   /api/hyperfleet/v1/nodepools:
@@ -721,6 +761,8 @@ paths:
             application/problem+json:
               schema:
                 $ref: '#/components/schemas/Error'
+      tags:
+        - NodePools
       security:
         - BearerAuth: []
 components:

schemas/core/swagger.yaml

@@ -74,6 +74,9 @@ paths:
             $ref: '#/definitions/Error'
       security:
         - BearerAuth: []
+      tags:
+        - Clusters
+      description: Returns a list of all clusters.
       operationId: getClusters
       summary: List clusters
     post:
@@ -103,6 +106,8 @@ paths:
             $ref: '#/definitions/Error'
       security:
         - BearerAuth: []
+      tags:
+        - Clusters
       description: >-
         Create a new cluster resource.
 
@@ -215,6 +220,8 @@ paths:
             $ref: '#/definitions/Error'
       security:
         - BearerAuth: []
+      tags:
+        - Clusters
       description: >-
         Marks the cluster for deletion by setting deleted_time to the current
         time, cascades to its nodepools.
@@ -255,6 +262,9 @@ paths:
             $ref: '#/definitions/Error'
       security:
         - BearerAuth: []
+      tags:
+        - Clusters
+      description: Returns a single cluster by its ID.
       operationId: getClusterById
       summary: Get cluster by ID
     patch:
@@ -291,6 +301,8 @@ paths:
             $ref: '#/definitions/Error'
       security:
         - BearerAuth: []
+      tags:
+        - Clusters
       description: Patch a specific cluster by ID
       operationId: patchClusterById
       summary: Patch cluster by ID
@@ -351,6 +363,8 @@ paths:
             $ref: '#/definitions/Error'
       security:
         - BearerAuth: []
+      tags:
+        - NodePools
       description: Returns the list of all nodepools for a cluster
       operationId: getNodePoolsByClusterId
       summary: List all nodepools for cluster
@@ -388,6 +402,8 @@ paths:
             $ref: '#/definitions/Error'
       security:
         - BearerAuth: []
+      tags:
+        - NodePools
       description: Create a NodePool for a cluster
       operationId: createNodePool
       summary: Create nodepool
@@ -501,6 +517,8 @@ paths:
             $ref: '#/definitions/Error'
       security:
         - BearerAuth: []
+      tags:
+        - NodePools
       description: >-
         Marks the nodepool for deletion by setting deleted_time and deleted_by.
         Does not affect the parent cluster.
@@ -536,6 +554,8 @@ paths:
             $ref: '#/definitions/Error'
       security:
         - BearerAuth: []
+      tags:
+        - NodePools
       description: Returns specific nodepool
       operationId: getNodePoolById
       summary: Get nodepool by ID
@@ -578,6 +598,8 @@ paths:
             $ref: '#/definitions/Error'
       security:
         - BearerAuth: []
+      tags:
+        - NodePools
       description: Patch a specific nodepool within a cluster
       operationId: patchNodePoolById
       summary: Patch nodepool by ID
@@ -640,6 +662,8 @@ paths:
           description: An unexpected error response.
           schema:
             $ref: '#/definitions/Error'
+      tags:
+        - NodePool statuses
       description: Returns adapter status reports for this nodepool
       operationId: getNodePoolsStatuses
       summary: List all adapter statuses for nodepools
@@ -679,6 +703,8 @@ paths:
           description: The request conflicts with the current state of the server.
       security:
         - BearerAuth: []
+      tags:
+        - NodePool statuses
       description: >-
         Adapter creates or updates its status report for this nodepool.
 
@@ -727,6 +753,11 @@ paths:
           description: The request conflicts with the current state of the server.
       security:
         - BearerAuth: []
+      tags:
+        - NodePool statuses
+      description: >-
+        Idempotent upsert of an adapter status for this nodepool. Use instead of
+        POST when the adapter name is known upfront.
       operationId: putNodePoolStatuses
       summary: Adapter creates or updates resource nodepool status
   '/api/hyperfleet/v1/clusters/{cluster_id}/statuses':
@@ -783,6 +814,8 @@ paths:
           description: The server cannot find the requested resource.
       security:
         - BearerAuth: []
+      tags:
+        - Cluster statuses
       description: Returns adapter status reports for this cluster
       operationId: getClusterStatuses
       summary: List all adapter statuses for cluster
@@ -817,6 +850,8 @@ paths:
           description: The request conflicts with the current state of the server.
       security:
         - BearerAuth: []
+      tags:
+        - Cluster statuses
       description: >-
         Adapter creates or updates its status report for this cluster.
 
@@ -860,6 +895,11 @@ paths:
           description: The request conflicts with the current state of the server.
       security:
         - BearerAuth: []
+      tags:
+        - Cluster statuses
+      description: >-
+        Idempotent upsert of an adapter status for this cluster. Use instead of
+        POST when the adapter name is known upfront.
       operationId: putClusterStatuses
       summary: Adapter creates or updates resource cluster status
   /api/hyperfleet/v1/nodepools:
@@ -914,6 +954,8 @@ paths:
             $ref: '#/definitions/Error'
       security:
         - BearerAuth: []
+      tags:
+        - NodePools
       description: Returns the list of all nodepools
       operationId: getNodePools
       summary: List all nodepools for cluster
@@ -1973,7 +2015,11 @@ securityDefinitions:
     in: header
     name: Authorization
     type: apiKey
-tags: []
+tags:
+  - name: Clusters
+  - name: Cluster statuses
+  - name: NodePool statuses
+  - name: NodePools
 x-components:
   parameters:
     QueryParams.order: