From ac492d1ad68c8ecca3ee03b50bc26d9d01366831 Mon Sep 17 00:00:00 2001 From: Pierre Sauvage Date: Fri, 29 May 2026 12:15:39 +0200 Subject: [PATCH] docs: add missing swagger descriptions --- api/openapi/v3/definition/Catalog.yaml | 12 ++++++++++- api/openapi/v3/definition/Cluster.yaml | 21 +++++++++++++++++-- api/openapi/v3/definition/GitRepository.yaml | 8 +++++++ api/openapi/v3/definition/Namespace.yaml | 10 +++++++++ api/openapi/v3/definition/Project.yaml | 7 +++++++ api/openapi/v3/definition/ReleaseInfo.yaml | 12 ++++++++++- api/openapi/v3/definition/UserProfile.yaml | 9 +++++++- api/openapi/v3/paths/catalogs/catalogs.yaml | 3 ++- .../v3/paths/catalogs/package-by-name.yaml | 4 ++-- .../v3/paths/catalogs/package-definition.yaml | 3 ++- .../v3/paths/catalogs/package-schema.yaml | 3 ++- .../catalogs/package-versions-by-name.yaml | 3 ++- api/openapi/v3/paths/clusters/namespaces.yaml | 2 +- api/openapi/v3/paths/k8s/release-by-name.yaml | 6 ++++-- api/openapi/v3/paths/projects/projects.yaml | 6 +++--- 15 files changed, 92 insertions(+), 17 deletions(-) diff --git a/api/openapi/v3/definition/Catalog.yaml b/api/openapi/v3/definition/Catalog.yaml index 8ce4f67..59834a1 100644 --- a/api/openapi/v3/definition/Catalog.yaml +++ b/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,26 +11,35 @@ 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: @@ -37,4 +47,4 @@ properties: properties: name: type: string - + description: Name of the package diff --git a/api/openapi/v3/definition/Cluster.yaml b/api/openapi/v3/definition/Cluster.yaml index b181438..a65792a 100644 --- a/api/openapi/v3/definition/Cluster.yaml +++ b/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,16 +65,21 @@ 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 @@ -70,8 +87,8 @@ 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 diff --git a/api/openapi/v3/definition/GitRepository.yaml b/api/openapi/v3/definition/GitRepository.yaml index de3bb1c..8a27b65 100644 --- a/api/openapi/v3/definition/GitRepository.yaml +++ b/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 diff --git a/api/openapi/v3/definition/Namespace.yaml b/api/openapi/v3/definition/Namespace.yaml index 9763a90..295ec6a 100644 --- a/api/openapi/v3/definition/Namespace.yaml +++ b/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" diff --git a/api/openapi/v3/definition/Project.yaml b/api/openapi/v3/definition/Project.yaml index 8e27644..6572b61 100644 --- a/api/openapi/v3/definition/Project.yaml +++ b/api/openapi/v3/definition/Project.yaml @@ -1,4 +1,5 @@ type: object +description: An OKDP project, materialized as a Kubernetes namespace with OKDP-specific metadata. xml: name: Project required: @@ -6,22 +7,28 @@ required: 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" diff --git a/api/openapi/v3/definition/ReleaseInfo.yaml b/api/openapi/v3/definition/ReleaseInfo.yaml index 4443caf..465da08 100644 --- a/api/openapi/v3/definition/ReleaseInfo.yaml +++ b/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://: tag: type: string + description: Part of the OCI url oci://: 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 diff --git a/api/openapi/v3/definition/UserProfile.yaml b/api/openapi/v3/definition/UserProfile.yaml index 985d654..115386b 100644 --- a/api/openapi/v3/definition/UserProfile.yaml +++ b/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 diff --git a/api/openapi/v3/paths/catalogs/catalogs.yaml b/api/openapi/v3/paths/catalogs/catalogs.yaml index c212b02..b656bdd 100644 --- a/api/openapi/v3/paths/catalogs/catalogs.yaml +++ b/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 diff --git a/api/openapi/v3/paths/catalogs/package-by-name.yaml b/api/openapi/v3/paths/catalogs/package-by-name.yaml index 9219f68..fed114a 100644 --- a/api/openapi/v3/paths/catalogs/package-by-name.yaml +++ b/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: diff --git a/api/openapi/v3/paths/catalogs/package-definition.yaml b/api/openapi/v3/paths/catalogs/package-definition.yaml index 4b5a70d..962d436 100644 --- a/api/openapi/v3/paths/catalogs/package-definition.yaml +++ b/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 diff --git a/api/openapi/v3/paths/catalogs/package-schema.yaml b/api/openapi/v3/paths/catalogs/package-schema.yaml index c84944b..c5338a9 100644 --- a/api/openapi/v3/paths/catalogs/package-schema.yaml +++ b/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 diff --git a/api/openapi/v3/paths/catalogs/package-versions-by-name.yaml b/api/openapi/v3/paths/catalogs/package-versions-by-name.yaml index 41021ca..ce9f79f 100644 --- a/api/openapi/v3/paths/catalogs/package-versions-by-name.yaml +++ b/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 diff --git a/api/openapi/v3/paths/clusters/namespaces.yaml b/api/openapi/v3/paths/clusters/namespaces.yaml index fc20e5e..bdbf5f6 100644 --- a/api/openapi/v3/paths/clusters/namespaces.yaml +++ b/api/openapi/v3/paths/clusters/namespaces.yaml @@ -80,7 +80,7 @@ put: required: true description: Cluster ID requestBody: - description: Namespace object to be created + description: Namespace object to be updated required: true content: application/json: diff --git a/api/openapi/v3/paths/k8s/release-by-name.yaml b/api/openapi/v3/paths/k8s/release-by-name.yaml index c8ccca6..b7978c5 100644 --- a/api/openapi/v3/paths/k8s/release-by-name.yaml +++ b/api/openapi/v3/paths/k8s/release-by-name.yaml @@ -1,7 +1,8 @@ get: summary: Get the deployed release by name description: | - Get the deployed release by name + Returns a single KuboCD release deployed in the given namespace, + identified by its name. tags: - k8s operationId: GetK8sRelease @@ -42,7 +43,8 @@ get: delete: summary: Delete the KuboCD release in kubernetes description: | - Delete the KuboCD release in kubernetes + Deletes the KuboCD release identified by its name from the given + namespace of the target cluster. tags: - k8s operationId: DeleteK8sRelease diff --git a/api/openapi/v3/paths/projects/projects.yaml b/api/openapi/v3/paths/projects/projects.yaml index d7017a3..d671008 100644 --- a/api/openapi/v3/paths/projects/projects.yaml +++ b/api/openapi/v3/paths/projects/projects.yaml @@ -31,7 +31,7 @@ get: put: summary: Update an existing OKDP project description: | - Update an existing OKDP project + Updates an existing OKDP project in the given cluster. tags: - projects operationId: UpdateProject @@ -43,7 +43,7 @@ put: required: true description: Cluster ID requestBody: - description: Project object to be created + description: Project object to be updated required: true content: application/json: @@ -68,7 +68,7 @@ put: post: summary: Create OKDP project description: | - Create OKDP project + Creates a new OKDP project in the given cluster. tags: - projects operationId: CreateProject