From 325bca4af391cf4966dec5518b578e6600fd936c Mon Sep 17 00:00:00 2001 From: Gabriel Adrian Samfira Date: Tue, 12 Aug 2025 09:17:16 +0000 Subject: [PATCH] Add swagger annotations and updates Add swagger annotations to models to allow generating a full swagger definition. This will help generate clients in other languages if needed. Signed-off-by: Gabriel Adrian Samfira --- apiserver/params/params.go | 1 + params/params.go | 37 ++++++++++++++++++++++++++++++++++++- params/requests.go | 21 +++++++++++++++++++++ 3 files changed, 58 insertions(+), 1 deletion(-) diff --git a/apiserver/params/params.go b/apiserver/params/params.go index 7aee3bd2..ec42fab6 100644 --- a/apiserver/params/params.go +++ b/apiserver/params/params.go @@ -14,6 +14,7 @@ package params +// swagger:model APIErrorResponse // APIErrorResponse holds information about an error, returned by the API type APIErrorResponse struct { Error string `json:"error"` diff --git a/params/params.go b/params/params.go index 9cd4fc83..50e26d26 100644 --- a/params/params.go +++ b/params/params.go @@ -172,6 +172,7 @@ const ( MessageTypeJobAvailable = "JobAvailable" ) +// swagger:model StatusMessage type StatusMessage struct { CreatedAt time.Time `json:"created_at,omitempty"` Message string `json:"message,omitempty"` @@ -179,6 +180,7 @@ type StatusMessage struct { EventLevel EventLevel `json:"event_level,omitempty"` } +// swagger:model EntityEvent type EntityEvent struct { ID uint `json:"id,omitempty"` CreatedAt time.Time `json:"created_at,omitempty"` @@ -188,6 +190,7 @@ type EntityEvent struct { Message string `json:"message,omitempty"` } +// swagger:model Instance type Instance struct { // ID is the database ID of this instance. ID string `json:"id,omitempty"` @@ -282,6 +285,7 @@ func (i Instance) GetID() string { } // used by swagger client generated code +// swagger:model Instances type Instances []Instance type BootstrapInstance struct { @@ -352,6 +356,7 @@ type Tag struct { Name string `json:"name,omitempty"` } +// swagger:model Pool type Pool struct { RunnerPrefix @@ -376,7 +381,7 @@ type Pool struct { EnterpriseID string `json:"enterprise_id,omitempty"` EnterpriseName string `json:"enterprise_name,omitempty"` - Endpoint ForgeEndpoint `json:"forge_type,omitempty"` + Endpoint ForgeEndpoint `json:"endpoint,omitempty"` RunnerBootstrapTimeout uint `json:"runner_bootstrap_timeout,omitempty"` CreatedAt time.Time `json:"created_at,omitempty"` @@ -487,11 +492,16 @@ func (p *Pool) HasRequiredLabels(set []string) bool { } // used by swagger client generated code +// swagger:model Pools type Pools []Pool +// swagger:model ScaleSet type ScaleSet struct { RunnerPrefix + CreatedAt time.Time `json:"created_at,omitempty"` + UpdatedAt time.Time `json:"updated_at,omitempty"` + ID uint `json:"id,omitempty"` ScaleSetID int `json:"scale_set_id,omitempty"` Name string `json:"name,omitempty"` @@ -511,6 +521,8 @@ type ScaleSet struct { Instances []Instance `json:"instances,omitempty"` DesiredRunnerCount int `json:"desired_runner_count,omitempty"` + Endpoint ForgeEndpoint `json:"endpoint,omitempty"` + RunnerBootstrapTimeout uint `json:"runner_bootstrap_timeout,omitempty"` // ExtraSpecs is an opaque raw json that gets sent to the provider // as part of the bootstrap params for instances. It can contain @@ -593,8 +605,10 @@ func (p *ScaleSet) RunnerTimeout() uint { } // used by swagger client generated code +// swagger:model ScaleSets type ScaleSets []ScaleSet +// swagger:model Repository type Repository struct { ID string `json:"id,omitempty"` Owner string `json:"owner,omitempty"` @@ -666,8 +680,10 @@ func (r Repository) String() string { } // used by swagger client generated code +// swagger:model Repositories type Repositories []Repository +// swagger:model Organization type Organization struct { ID string `json:"id,omitempty"` Name string `json:"name,omitempty"` @@ -724,8 +740,10 @@ func (o Organization) GetBalancerType() PoolBalancerType { } // used by swagger client generated code +// swagger:model Organizations type Organizations []Organization +// swagger:model Enterprise type Enterprise struct { ID string `json:"id,omitempty"` Name string `json:"name,omitempty"` @@ -782,9 +800,11 @@ func (e Enterprise) GetBalancerType() PoolBalancerType { } // used by swagger client generated code +// swagger:model Enterprises type Enterprises []Enterprise // Users holds information about a particular user +// swagger:model User type User struct { ID string `json:"id,omitempty"` CreatedAt time.Time `json:"created_at,omitempty"` @@ -801,10 +821,12 @@ type User struct { // JWTResponse holds the JWT token returned as a result of a // successful auth +// swagger:model JWTResponse type JWTResponse struct { Token string `json:"token,omitempty"` } +// swagger:model ControllerInfo type ControllerInfo struct { // ControllerID is the unique ID of this controller. This ID gets generated // automatically on controller init. @@ -857,6 +879,7 @@ func (c *ControllerInfo) JobBackoff() time.Duration { return time.Duration(int64(c.MinimumJobAgeBackoff)) } +// swagger:model GithubRateLimit type GithubRateLimit struct { Limit int `json:"limit,omitempty"` Used int `json:"used,omitempty"` @@ -875,6 +898,7 @@ func (g GithubRateLimit) ResetAt() time.Time { return time.Unix(g.Reset, 0) } +// swagger:model ForgeCredentials type ForgeCredentials struct { ID uint `json:"id,omitempty"` Name string `json:"name,omitempty"` @@ -1000,8 +1024,10 @@ func (g ForgeCredentials) RootCertificateBundle() (CertificateBundle, error) { } // used by swagger client generated code +// swagger:model Credentials type Credentials []ForgeCredentials +// swagger:model Provider type Provider struct { Name string `json:"name,omitempty"` ProviderType ProviderType `json:"type,omitempty"` @@ -1009,8 +1035,10 @@ type Provider struct { } // used by swagger client generated code +// swagger:model Providers type Providers []Provider +// swagger:model PoolManagerStatus type PoolManagerStatus struct { IsRunning bool `json:"running,omitempty"` FailureReason string `json:"failure_reason,omitempty"` @@ -1032,6 +1060,7 @@ func (p RunnerPrefix) GetRunnerPrefix() string { return p.Prefix } +// swagger:model Job type Job struct { // ID is the ID of the job. ID int64 `json:"id,omitempty"` @@ -1086,14 +1115,17 @@ type Job struct { UpdatedAt time.Time `json:"updated_at,omitempty"` } +// swagger:model Jobs // used by swagger client generated code type Jobs []Job +// swagger:model InstallWebhookParams type InstallWebhookParams struct { WebhookEndpointType WebhookEndpointType `json:"webhook_endpoint_type,omitempty"` InsecureSSL bool `json:"insecure_ssl,omitempty"` } +// swagger:model HookInfo type HookInfo struct { ID int64 `json:"id,omitempty"` URL string `json:"url,omitempty"` @@ -1106,6 +1138,7 @@ type CertificateBundle struct { RootCertificates map[string][]byte `json:"root_certificates,omitempty"` } +// swagger:model ForgeEntity type UpdateSystemInfoParams struct { OSName string `json:"os_name,omitempty"` OSVersion string `json:"os_version,omitempty"` @@ -1194,8 +1227,10 @@ func (g ForgeEntity) GetIDAsUUID() (uuid.UUID, error) { } // used by swagger client generated code +// swagger:model ForgeEndpoints type ForgeEndpoints []ForgeEndpoint +// swagger:model ForgeEndpoint type ForgeEndpoint struct { Name string `json:"name,omitempty"` Description string `json:"description,omitempty"` diff --git a/params/requests.go b/params/requests.go index 3f2fcfab..3f4e1737 100644 --- a/params/requests.go +++ b/params/requests.go @@ -39,6 +39,7 @@ type InstanceRequest struct { OSVersion string `json:"os_version"` } +// swagger:model CreateRepoParams type CreateRepoParams struct { Owner string `json:"owner,omitempty"` Name string `json:"name,omitempty"` @@ -80,6 +81,7 @@ func (c *CreateRepoParams) Validate() error { return nil } +// swagger:model CreateOrgParams type CreateOrgParams struct { Name string `json:"name,omitempty"` CredentialsName string `json:"credentials_name,omitempty"` @@ -115,6 +117,7 @@ func (c *CreateOrgParams) Validate() error { return nil } +// swagger:model CreateEnterpriseParams type CreateEnterpriseParams struct { Name string `json:"name,omitempty"` CredentialsName string `json:"credentials_name,omitempty"` @@ -143,6 +146,7 @@ func (c *CreateEnterpriseParams) Validate() error { // NewUserParams holds the needed information to create // a new user +// swagger:model NewUserParams type NewUserParams struct { Email string `json:"email,omitempty"` Username string `json:"username,omitempty"` @@ -152,6 +156,7 @@ type NewUserParams struct { Enabled bool `json:"-"` } +// swagger:model UpdatePoolParams type UpdatePoolParams struct { RunnerPrefix @@ -189,6 +194,7 @@ type CreateInstanceParams struct { JitConfiguration map[string]string `json:"jit_configuration,omitempty"` } +// swagger:model CreatePoolParams type CreatePoolParams struct { RunnerPrefix @@ -263,6 +269,7 @@ type UpdateUserParams struct { Enabled *bool `json:"enabled,omitempty"` } +// swagger:model PasswordLoginParams // PasswordLoginParams holds information used during // password authentication, that will be passed to a // password login function @@ -279,6 +286,7 @@ func (p PasswordLoginParams) Validate() error { return nil } +// swagger:model UpdateEntityParams type UpdateEntityParams struct { CredentialsName string `json:"credentials_name,omitempty"` WebhookSecret string `json:"webhook_secret,omitempty"` @@ -291,6 +299,7 @@ type InstanceUpdateMessage struct { AgentID *int64 `json:"agent_id,omitempty"` } +// swagger:model CreateGithubEndpointParams type CreateGithubEndpointParams struct { Name string `json:"name,omitempty"` Description string `json:"description,omitempty"` @@ -358,6 +367,7 @@ func (c CreateGithubEndpointParams) Validate() error { return nil } +// swagger:model UpdateGithubEndpointParams type UpdateGithubEndpointParams struct { Description *string `json:"description,omitempty"` APIBaseURL *string `json:"api_base_url,omitempty"` @@ -416,10 +426,12 @@ func (u UpdateGithubEndpointParams) Validate() error { return nil } +// swagger:model GithubPAT type GithubPAT struct { OAuth2Token string `json:"oauth2_token,omitempty"` } +// swagger:model GithubApp type GithubApp struct { AppID int64 `json:"app_id,omitempty"` InstallationID int64 `json:"installation_id,omitempty"` @@ -452,6 +464,7 @@ func (g GithubApp) Validate() error { return nil } +// swagger:model CreateGithubCredentialsParams type CreateGithubCredentialsParams struct { Name string `json:"name,omitempty"` Description string `json:"description,omitempty"` @@ -491,6 +504,7 @@ func (c CreateGithubCredentialsParams) Validate() error { return nil } +// swagger:model UpdateGithubCredentialsParams type UpdateGithubCredentialsParams struct { Name *string `json:"name,omitempty"` Description *string `json:"description,omitempty"` @@ -518,6 +532,7 @@ func (u UpdateGithubCredentialsParams) Validate() error { return nil } +// swagger:model UpdateControllerParams type UpdateControllerParams struct { MetadataURL *string `json:"metadata_url,omitempty"` CallbackURL *string `json:"callback_url,omitempty"` @@ -550,6 +565,7 @@ func (u UpdateControllerParams) Validate() error { return nil } +// swagger:model CreateScaleSetParams type CreateScaleSetParams struct { RunnerPrefix @@ -602,6 +618,7 @@ func (s *CreateScaleSetParams) Validate() error { return nil } +// swagger:model UpdateScaleSetParams type UpdateScaleSetParams struct { RunnerPrefix @@ -623,6 +640,7 @@ type UpdateScaleSetParams struct { ExtendedState *string `json:"extended_state"` } +// swagger:model CreateGiteaEndpointParams type CreateGiteaEndpointParams struct { Name string `json:"name,omitempty"` Description string `json:"description,omitempty"` @@ -674,6 +692,7 @@ func (c CreateGiteaEndpointParams) Validate() error { return nil } +// swagger:model UpdateGiteaEndpointParams type UpdateGiteaEndpointParams struct { Description *string `json:"description,omitempty"` APIBaseURL *string `json:"api_base_url,omitempty"` @@ -719,6 +738,7 @@ func (u UpdateGiteaEndpointParams) Validate() error { return nil } +// swagger:model CreateGiteaCredentialsParams type CreateGiteaCredentialsParams struct { Name string `json:"name,omitempty"` Description string `json:"description,omitempty"` @@ -752,6 +772,7 @@ func (c CreateGiteaCredentialsParams) Validate() error { return nil } +// swagger:model UpdateGiteaCredentialsParams type UpdateGiteaCredentialsParams struct { Name *string `json:"name,omitempty"` Description *string `json:"description,omitempty"`