docs: add missing swagger descriptions

api/openapi/v3/definition/Catalog.yaml

@@ -1,4 +1,5 @@
 type: object
+description: A package catalog backed by an OCI registry.
 xml:
   name: Catalog
 required:
@@ -10,31 +11,40 @@ required:
 properties:
   id:
     type: string
+    description: Unique identifier of the catalog
     x-go-name: ID
   name:
     type: string
+    description: Human-readable name of the catalog
   description:
     type: string
+    description: Short description of the catalog
   repoUrl:
     type: string
     format: uri
+    description: URL of the OCI registry backing the catalog
     x-go-name: repoURL
   credentials:
     type: object
+    description: Credentials used to authenticate to the OCI registry
     properties:
       robotAccountName:
         type: string
+        description: Robot account name used to authenticate
       robotAccountToken:
         type: string
+        description: Robot account token used to authenticate
       dockerconfigjson:
         type: string
+        description: Base64-encoded Docker config JSON credentials
   packages:
     type: array
+    description: Packages exposed by the catalog
     items:
       type: object
       required:
       - name
       properties:
         name:
           type: string
-
+          description: Name of the package

api/openapi/v3/definition/Cluster.yaml

@@ -1,4 +1,5 @@
 type: object
+description: A Kubernetes cluster registered in the OKDP server and the credentials used to connect to it.
 xml:
   name: Cluster
 required:
@@ -9,13 +10,17 @@ required:
 properties:
   id:
     type: string
+    description: Unique identifier of the cluster
     x-go-name: ID
   name:
     type: string
+    description: Human-readable name of the cluster
   env:
     type: string
+    description: Environment the cluster belongs to
   auth:
     type: object
+    description: Authentication method used to connect to the cluster (exactly one must be provided)
     oneOf:
       - required: [inCluster]
       - required: [kubeconfig]
@@ -24,8 +29,10 @@ properties:
     properties:
       inCluster:
         type: boolean
+        description: Use the in-cluster service account credentials
       kubeconfig:
         type: object
+        description: Authenticate using a kubeconfig file
         required:
           - apiServer
           - path
@@ -35,15 +42,20 @@ properties:
           apiServer:
             type: string
             format: uri
+            description: URL of the Kubernetes API server
             x-go-name: APIServer
           path:
             type: string
+            description: Path to the kubeconfig file
           context:
             type: string
+            description: Name of the kubeconfig context to use
           insecureSkipTlsVerify:
             type: boolean
+            description: Skip TLS verification of the API server certificate
       certificate:
         type: object
+        description: Authenticate using a client certificate
         required:
           - apiServer
           - clientKey
@@ -53,25 +65,30 @@ properties:
           apiServer:
             type: string
             format: uri
+            description: URL of the Kubernetes API server
             x-go-name: APIServer
           clientKey:
             type: string
+            description: PEM-encoded client private key
           clientCert:
             type: string
+            description: PEM-encoded client certificate
           caCert:
             type: string
+            description: PEM-encoded certificate authority bundle
             x-go-name: CACert
       bearer:
         type: object
+        description: Authenticate using a bearer token
         required:
           - apiServer
           - bearerToken
         properties:
           apiServer:
             type: string
             format: uri
+            description: URL of the Kubernetes API server
             x-go-name: APIServer
           bearerToken:
             type: string
-
-
+            description: Bearer token used to authenticate to the API server

api/openapi/v3/definition/GitRepository.yaml

@@ -1,4 +1,5 @@
 type: object
+description: A FluxCD git repository (Kustomization) used as a source for KuboCD releases.
 xml:
   name: GitRepository
 required:
@@ -12,19 +13,26 @@ properties:
   repoUrl:
     type: string
     format: uri
+    description: URL of the git repository
     x-go-name: repoURL
   ref:
     type: string
+    description: Git reference (branch, tag or commit) to track
   name:
     type: string
+    description: Name of the FluxCD Kustomization
   namespace:
     type: string
+    description: Namespace of the FluxCD Kustomization
   path:
     type: string
+    description: Path within the repository watched by the Kustomization
   credentials:
     type: object
+    description: Credentials used to access the git repository
     required:
     - "secretRef"
     properties:
       secretRef:
         type: string
+        description: Name of the Secret holding the git credentials

api/openapi/v3/definition/Namespace.yaml

@@ -1,4 +1,5 @@
 type: object
+description: A Kubernetes namespace.
 xml:
   name: Namespace
 required:
@@ -8,40 +9,49 @@ required:
 properties:
   apiVersion:
     type: string
+    description: APIVersion of the namespace resource
     example: "v1"
   kind:
     type: string
     enum: ["Namespace"]
+    description: Kind of the resource, always "Namespace"
     example: "Namespace"
   metadata:
     type: object
+    description: Standard object metadata
     required:
       - name
     properties:
       name:
         type: string
+        description: Name of the namespace
         example: "my-namespace"
       labels:
         type: object
         additionalProperties:
           type: string
+        description: Key-value labels attached to the namespace
         example:
           environment: "dev"
       annotations:
         type: object
         additionalProperties:
           type: string
+        description: Arbitrary annotations attached to the namespace
         example:
           owner: "team-a"
       creationTimestamp:
         type: string
         format: date-time
         readOnly: true
+        description: Creation timestamp of the namespace
         example: "2025-06-12T14:00:00Z"
   status:
     type: object
+    description: Observed status of the namespace
     properties:
       phase:
         type: string
         enum: ["Active", "Terminating"]
+        description: Lifecycle phase of the namespace
         example: "Active"

api/openapi/v3/definition/Project.yaml

@@ -1,27 +1,34 @@
 type: object
+description: An OKDP project, materialized as a Kubernetes namespace with OKDP-specific metadata.
 xml:
   name: Project
 required:
   - name
 properties:
   name:
     type: string
+    description: Unique name of the project
     example: "my-project1"
   displayName:
     type: string
+    description: Human-readable name of the project
     example: "My Project 1"
   environment:
     type: string
+    description: Environment the project belongs to
     example: "my-project1"
   description:
     type: string
+    description: Short description of the project
     example: "my-project"
   creationTimestamp:
     type: string
     format: date-time
     readOnly: true
+    description: Creation timestamp of the project
     example: "2025-06-12T14:00:00Z"
   status:
     type: string
     enum: ["Active", "Terminating"]
+    description: Lifecycle status of the project
     example: "Active"

api/openapi/v3/definition/ReleaseInfo.yaml

@@ -1,4 +1,5 @@
 type: object
+description: Summary information about a KuboCD release stored in a git repository.
 xml:
   name: ReleaseInfo
 required:
@@ -8,28 +9,37 @@ required:
 properties:
   name:
     type: string
+    description: Name of the release
   namespace:
     type: string
+    description: Namespace the release is deployed to
   description:
-      type: string
+    type: string
+    description: Short description of the release
   package:
     type: object
+    description: The OCI package deployed by the release
     required:
       - "repository"
       - "tag"
     properties:
       repository:
         type: string
+        description: Part of the OCI url oci://<repository>:<tag>
       tag:
         type: string
+        description: Part of the OCI url oci://<repository>:<tag>
   git:
     type: object
+    description: Location of the release manifest in the git repository
     required:
       - "path"
       - "url"
     properties:
       path:
         type: string
+        description: Path of the release manifest within the repository
       url:
         type: string
+        description: URL of the git repository
         x-go-name: URL

api/openapi/v3/definition/UserProfile.yaml

@@ -1,7 +1,8 @@
 type: object
+description: Profile of the authenticated user, resolved from the OIDC token.
 xml:
   name: UserProfile
-required: 
+required:
 - sub
 - login
 - name
@@ -11,18 +12,24 @@ required:
 properties:
   sub:
     type: string
+    description: Subject (unique user identifier) from the OIDC token
     x-go-name: subject
   login:
     type: string
+    description: User login name
   name:
     type: string
+    description: User display name
   email:
     type: string
+    description: User email address
   groups:
     type: array
     items:
       type: string
+    description: Groups the user belongs to
   roles:
     type: array
     items:
       type: string
+    description: Roles granted to the user

api/openapi/v3/paths/catalogs/catalogs.yaml

@@ -1,7 +1,8 @@
 get:
   summary: List all catalogs
   description: |
-    List all catalogs
+    Returns all package catalogs (OCI registries) configured in the OKDP
+    server.
   tags:
     - catalogs
   operationId: ListCatalogs

api/openapi/v3/paths/catalogs/package-by-name.yaml

@@ -1,7 +1,7 @@
 get:
   summary: Get package by catalog id and package name
   description: |
-    Get package by catalog id and package name
+    Returns a single package, identified by its name, from the given catalog.
   tags:
     - catalogs
   operationId: GetPackage
@@ -20,7 +20,7 @@ get:
       description: Package name
   responses:
     '200':
-      description: Packages information
+      description: Package information
       content:
         application/json:
           schema:

api/openapi/v3/paths/catalogs/package-definition.yaml

@@ -1,7 +1,8 @@
 get:
   summary: Get package definition
   description: |
-    Get package definition
+    Returns the full definition of a specific package version from the
+    given catalog.
   tags:
     - catalogs
   operationId: GetPackageDefinition

api/openapi/v3/paths/catalogs/package-schema.yaml

@@ -1,7 +1,8 @@
 get:
   summary: Get package schema (parameters, context, etc)
   description: |
-    Get package schema (parameters, context, etc)
+    Returns the configuration schema (parameters, context, etc.) for a
+    specific package version, suitable for rendering a configuration form.
   tags:
     - catalogs
   operationId: GetPackageSchema

api/openapi/v3/paths/catalogs/package-versions-by-name.yaml

@@ -1,7 +1,8 @@
 get:
   summary: List versions for a specific package
   description: |
-    List versions for a specific package
+    Returns the list of available versions for the named package in the
+    given catalog.
   tags:
     - catalogs
   operationId: GetPackageVersions