feat(ws): complete api swagger documentation across workspaces, namespaces, and workspacekinds

[Mohamed-ben-khemis]

Closes #46

Summary

This PR continues the Swagger integration by adding complete Swagger documentation for all API endpoints.

Changes Implemented

• Complete API Documentation: Added Swagger annotations for:
  • Health Check endpoint
  • Namespaces endpoint
  • Workspaces (list, get, create, delete) endpoints
  • WorkspaceKinds (list, get) endpoints
• Structured and Consistent Annotations: Ensured proper formatting using tab-indented docstrings to comply with gofmt.
• Documentation Output: Swagger JSON/YAML is generated consistently and served via /api/v1/swagger/index.html.

Notes

• Builds on top of the previous Swagger setup PR (#206).
• This brings full API coverage to the Swagger UI and facilitates interactive testing and easier onboarding for developers.

[ederign]

/assign @ederign

[andyatmiami]

workspace-kinds is not a valid URL segment - will result in 404. value should be workspacekinds

• additionally api/v1 segment appears 2x

vs.

$ curl --request GET   --url http://localhost:4000/api/v1/workspacekinds -I
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: application/json
Date: Fri, 02 May 2025 20:36:32 GMT
Transfer-Encoding: chunked

[google-oss-prow]

@andyatmiami: changing LGTM is restricted to collaborators

In response to this:

workspace-kinds is not a valid URL segment - will result in 404. value should be workspacekinds

vs.

$ curl --request GET   --url http://localhost:4000/api/v1/workspacekinds -I
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: application/json
Date: Fri, 02 May 2025 20:36:32 GMT
Transfer-Encoding: chunked

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[andyatmiami]

Looks like the workspaces path is mangled... api/v1 appears 2x

vs.

$ curl --request GET   --url http://localhost:4000/api/v1/workspaces -I
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: application/json
Date: Fri, 02 May 2025 20:39:51 GMT
Transfer-Encoding: chunked

[google-oss-prow]

@andyatmiami: changing LGTM is restricted to collaborators

In response to this:

Looks like the workspaces path is manged... api/v1 appears 2x

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[Mohamed-ben-khemis]

Looks like the workspaces path is mangled... api/v1 appears 2x

vs.

$ curl --request GET   --url http://localhost:4000/api/v1/workspaces -I
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: application/json
Date: Fri, 02 May 2025 20:39:51 GMT
Transfer-Encoding: chunked

Hi @andyatmiami, thanks for testing it out! 🙏

I’ve pushed a tiny update that resolves both of the problems you spotted:

Removed the hyphen in the WorkspaceKinds route (changed workspace‑kinds → workspacekinds) so it no longer 404s (Swagger treats path segments literally).

Eliminated the duplicate /api/v1 prefix by relying solely on swagger.SwaggerInfo.BasePath = "/api/v1" in docs.go, and dropping /api/v1 from each @router annotation.

[andyatmiami]

Verified all endpoints are operational within the Swagger UI.

[google-oss-prow]

@andyatmiami: changing LGTM is restricted to collaborators

In response to this:

Verified all endpoints are operational within the Swagger UI.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[ederign]

A minor comment inside but I guess we are good merge this as incremental work. We need this to unblock generation of types on backend.

[ederign]

/lgtm

[thesuperzapper]

/approve

[google-oss-prow]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: thesuperzapper

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [thesuperzapper]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[thesuperzapper]

/ok-to-test