Auto generate OpenAPI spec

[ppadti]

Description

This PR aims to generate the openapi spec. Added make cmd to generate open api spec and added checks in CI to test on each PR
Currently added for one handler to test and get reviews, once that is done, will convert all the endpoints

How Has This Been Tested?

make openapi cmd will generate swagger.yaml and swagger.json file for now

Merge criteria:

• All the commits have been signed-off (To pass the DCO check)

• The commits have meaningful messages
• Automated tests are provided as part of the PR for major new functionalities; testing instructions have been added in the PR body (for PRs involving changes that are not immediately obvious).
• The developer has manually tested the changes and verified that the changes work.
• Code changes follow the kubeflow contribution guidelines.
• For first time contributors: Please reach out to the Reviewers to ensure all tests are being run, ensuring the label ok-to-test has been added to the PR.

If you have UI changes

• The developer has added tests or explained why testing cannot be added.
• Included any necessary screenshots or gifs if it was a UI change.
• Verify that UI/UX changes conform the UX guidelines for Kubeflow.

[ppadti]

/assign @ederign

[ederign]

Thanks for working on this, Pushpa! This is a good start. I wanted to share some guidance based on how we implemented the same feature in the notebooks backend, which can serve as a reference.

Swag Command Enhancements

The current command:

$(SWAG) init -g cmd/main.go -o ../api/openapi --outputTypes json,yaml --parseDependency --parseInternal

Suggested improvements (see notebooks Makefile):

$(SWAG) fmt -g main.go -d $(SWAG_DIRS)
$(SWAG) init --parseDependency -q -g main.go -d $(SWAG_DIRS) --output openapi --outputTypes go,json,yaml --requiredByDefault

Key additions:

• swag fmt before init - formats annotations consistently
• --requiredByDefault - marks fields as required by default (better API contracts)
• --outputTypes go,json,yaml - generates docs.go which is needed for serving Swagger UI and programmatic access
• -d $(SWAG_DIRS) - explicitly specify directories to scan

Build Integration

Currently make openapi is a standalone target. I assume this is because we are starting it, right?

build: fmt vet openapi  ## swag runs on every build
run: fmt vet openapi    ## swag runs on every run  

IN future, let's make sure to add this to the build. This ensures the spec is always up-to-date and prevents drift. Let's include this in next PRs? Maybe we can generate a file 'on the side' of the current one until we don't finishes it?

Definition Names

The generated spec has fully-qualified type names:

"github_com_kubeflow_model-registry_ui_bff_internal_models.HealthCheckModel"

Compare to notebooks which generates clean names:

"health_check.HealthCheck"

This may require reorganizing how types are imported/referenced. See how notebooks structures its models in internal/models/ subdirectories.

Annotation Completeness

When extending to all endpoints, consider including (see workspaces_handler.go for examples):

• @Accept json directive
• Path parameters with examples: @Param namespace path string true "Namespace" extensions(x-example=kubeflow-user-example-com)
• All relevant HTTP error codes (401, 403, 404, 422, 500)
• Detailed descriptions for each response

Optional: Swagger UI Handler

The notebooks backend includes a swagger_handler.go that serves interactive Swagger UI documentation. This is helpful for local development and API exploration.

Let me know if you have questions about any of these suggestions!

@ppadti and again, thank you so much! This is denivitelly on the right direction! Just small tweaks and we can start to expand it to all endpoints

[google-oss-prow]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please ask for approval from ederign. For more information see the Kubernetes Code Review Process.

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

Details

Needs approval from an approver in each of these files:

• OWNERS

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