openapi

package
v1.16.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 6, 2026 License: Apache-2.0 Imports: 9 Imported by: 32

README

pkg/openapi

Intention

pkg/openapi is the platform's shared OpenAPI substrate. It provides the common schema fragments, generated types, embedded specification loading, and runtime route lookup machinery that other service APIs build on.

Most of the package is generated from the shared OpenAPI specification. That generated layer defines reusable schema fragments, enums, generic error shapes, resource metadata models, and the embedded spec-loading functions used by downstream service-specific OpenAPI packages.

The handwritten helpers layer is load-bearing runtime infrastructure for the platform middleware stack. In particular, FindRoute performs efficient path-based schema lookup from an already-routed Chi request, resolves the matching OpenAPI operation, and returns both route metadata and extracted path parameters.

That route metadata is then used to drive handler and middleware behavior from schema-defined data, including validation, authorization, CORS handling, auditing, and related request-processing decisions.

Invariants And Guard Rails

  • This package is shared OpenAPI contract infrastructure, not a generic HTTP utility package.
  • The generated schema and types here are intended to be imported and reused by service-specific OpenAPI packages rather than redefined independently.
  • The generated layer is the source of truth for the shared OpenAPI fragments it embeds. Manual edits belong in the specification or generation pipeline, not in generated files.
  • GetSwagger() exposes the embedded shared specification, and PathToRawSpec() exists to support external reference resolution for downstream generated OpenAPI packages using import-mapped shared schema fragments.
  • helpers.FindRoute() is part of the runtime contract of the platform middleware stack. It is not optional convenience code.
  • Route lookup is intentionally coupled to requests that have already been routed by Chi. That is a performance choice: the platform reuses the routed path context for efficient schema lookup rather than paying for a second generic route-resolution pass.
  • Middleware and handlers should derive schema-driven behavior from the resolved OpenAPI route rather than duplicate path logic separately.

Caveats

  • Most of this package is generated code, so the real design surface is smaller than the file count suggests.
  • The handwritten helper layer is small, but it is operationally critical because middleware behavior depends on correct route-to-schema resolution.
  • The package mixes static contract artifacts and runtime lookup logic. That is intentional for the platform, but it means the boundary is broader than "just generated types".
  • The route lookup logic is coupled to Chi routing semantics and the platform's middleware ordering by design. Using it outside an already-routed Chi request path is the wrong usage pattern, not a generally supported mode.

Documentation

Overview

Package openapi provides primitives to interact with the openapi HTTP API.

Code generated by github.com/oapi-codegen/oapi-codegen/v2 version v2.4.1 DO NOT EDIT.

Package openapi provides primitives to interact with the openapi HTTP API.

Code generated by github.com/oapi-codegen/oapi-codegen/v2 version v2.4.1 DO NOT EDIT.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GetSwagger 

func GetSwagger() (swagger *openapi3.T, err error)

GetSwagger returns the Swagger specification corresponding to the generated code in this file. The external references of Swagger specification are resolved. The logic of resolving external references is tightly connected to "import-mapping" feature. Externally referenced files must be embedded in the corresponding golang packages. Urls can be supported but this task was out of the scope.

func PathToRawSpec 

func PathToRawSpec(pathToFile string) map[string]func() ([]byte, error)

Constructs a synthetic filesystem for resolving external references when loading openapi specifications.

Types

type AuthorizationServerList added in v1.14.0 

type AuthorizationServerList = []string

AuthorizationServerList List of authorization servers that can grant access to the resource.

type BadRequestResponse 

type BadRequestResponse = Error

BadRequestResponse Generic error message, compatible with oauth2.

type BearerMethod added in v1.14.0 

type BearerMethod string

BearerMethod Bearer token transport method 

const (
	Body   BearerMethod = "body"
	Header BearerMethod = "header"
	Query  BearerMethod = "query"
)

Defines values for BearerMethod.

type BearerMethodList added in v1.14.0 

type BearerMethodList = []BearerMethod

BearerMethodList A set of bearer token transport methods supported by the protected endpoint.

type ConflictResponse 

type ConflictResponse = Error

ConflictResponse Generic error message, compatible with oauth2.

type Error 

type Error struct {
	// Error A terse error string expanding on the HTTP error code. Errors are based on the OAuth 2.02 specification, but are expanded with proprietary status codes for APIs other than those specified by OAuth 2.02.
	Error ErrorError `json:"error"`

	// ErrorDescription Verbose message describing the error.
	ErrorDescription string `json:"error_description"`

	// TraceId Unique trace identifier for the request.
	TraceId *string `json:"trace_id,omitempty"`
}

Error Generic error message, compatible with oauth2.

type ErrorError 

type ErrorError string

ErrorError A terse error string expanding on the HTTP error code. Errors are based on the OAuth 2.02 specification, but are expanded with proprietary status codes for APIs other than those specified by OAuth 2.02. 

const (
	AccessDenied          ErrorError = "access_denied"
	Conflict              ErrorError = "conflict"
	Forbidden             ErrorError = "forbidden"
	InvalidRequest        ErrorError = "invalid_request"
	MethodNotAllowed      ErrorError = "method_not_allowed"
	NotFound              ErrorError = "not_found"
	RequestEntityTooLarge ErrorError = "request_entity_too_large"
	ServerError           ErrorError = "server_error"
	UnprocessableContent  ErrorError = "unprocessable_content"
	UnsupportedMediaType  ErrorError = "unsupported_media_type"
)

Defines values for ErrorError.

type ForbiddenResponse 

type ForbiddenResponse = Error

ForbiddenResponse Generic error message, compatible with oauth2.

type InternalServerErrorResponse 

type InternalServerErrorResponse = Error

InternalServerErrorResponse Generic error message, compatible with oauth2.

type KubernetesLabelValue 

type KubernetesLabelValue = string

KubernetesLabelValue A valid Kubernetes label value, typically used for resource names that can be indexed in the database.

type NoReservedTags added in v1.15.0 

type NoReservedTags struct {
	Tags *[]struct {
		Name *interface{} `json:"name,omitempty"`
	} `json:"tags,omitempty"`
}

NoReservedTags Constrain tags to not have reserved names.

type NotFoundResponse 

type NotFoundResponse = Error

NotFoundResponse Generic error message, compatible with oauth2.

type OpenidProtectedResource added in v1.14.0 

type OpenidProtectedResource struct {
	// AuthorizationServers List of authorization servers that can grant access to the resource.
	AuthorizationServers AuthorizationServerList `json:"authorization_servers"`

	// BearerMethodsSupported A set of bearer token transport methods supported by the protected endpoint.
	BearerMethodsSupported BearerMethodList `json:"bearer_methods_supported"`

	// Resource The protected resource's scheme and hostname.
	Resource string `json:"resource"`

	// ScopesSupported A set of OIDC scopes that are required for authorization.
	ScopesSupported ScopeList `json:"scopes_supported"`
}

OpenidProtectedResource OpenID athentication server discovery configuration.

type OpenidProtectedResourceResponse added in v1.14.0 

type OpenidProtectedResourceResponse = OpenidProtectedResource

OpenidProtectedResourceResponse OpenID athentication server discovery configuration.

type OrganizationScopedResourceReadMetadata 

type OrganizationScopedResourceReadMetadata struct {
	// CreatedBy The user who created the resource.
	CreatedBy *string `json:"createdBy,omitempty"`

	// CreationTime The time the resource was created.
	CreationTime time.Time `json:"creationTime"`

	// DeletionTime The time the resource was deleted.
	DeletionTime *time.Time `json:"deletionTime,omitempty"`

	// Description The resource description, this optionally augments the name with more context.
	Description *string `json:"description,omitempty"`

	// HealthStatus The health state of a resource.
	HealthStatus ResourceHealthStatus `json:"healthStatus"`

	// Id The unique resource ID.
	Id string `json:"id"`

	// ModifiedBy The user who updated the resource.
	ModifiedBy *string `json:"modifiedBy,omitempty"`

	// ModifiedTime The time a resource was updated.
	ModifiedTime *time.Time `json:"modifiedTime,omitempty"`

	// Name A valid Kubernetes label value, typically used for resource names that can be
	// indexed in the database.
	Name KubernetesLabelValue `json:"name"`

	// OrganizationId The organization identifier the resource belongs to.
	OrganizationId string `json:"organizationId"`

	// ProvisioningStatus The provisioning state of a resource.
	ProvisioningStatus ResourceProvisioningStatus `json:"provisioningStatus"`

	// Tags A list of tags.
	Tags *TagList `json:"tags,omitempty"`
}

OrganizationScopedResourceReadMetadata defines model for organizationScopedResourceReadMetadata.

type ProjectScopedResourceReadMetadata 

type ProjectScopedResourceReadMetadata struct {
	// CreatedBy The user who created the resource.
	CreatedBy *string `json:"createdBy,omitempty"`

	// CreationTime The time the resource was created.
	CreationTime time.Time `json:"creationTime"`

	// DeletionTime The time the resource was deleted.
	DeletionTime *time.Time `json:"deletionTime,omitempty"`

	// Description The resource description, this optionally augments the name with more context.
	Description *string `json:"description,omitempty"`

	// HealthStatus The health state of a resource.
	HealthStatus ResourceHealthStatus `json:"healthStatus"`

	// Id The unique resource ID.
	Id string `json:"id"`

	// ModifiedBy The user who updated the resource.
	ModifiedBy *string `json:"modifiedBy,omitempty"`

	// ModifiedTime The time a resource was updated.
	ModifiedTime *time.Time `json:"modifiedTime,omitempty"`

	// Name A valid Kubernetes label value, typically used for resource names that can be
	// indexed in the database.
	Name KubernetesLabelValue `json:"name"`

	// OrganizationId The organization identifier the resource belongs to.
	OrganizationId string `json:"organizationId"`

	// ProjectId The project identifier the resource belongs to.
	ProjectId string `json:"projectId"`

	// ProvisioningStatus The provisioning state of a resource.
	ProvisioningStatus ResourceProvisioningStatus `json:"provisioningStatus"`

	// Tags A list of tags.
	Tags *TagList `json:"tags,omitempty"`
}

ProjectScopedResourceReadMetadata defines model for projectScopedResourceReadMetadata.

type ResourceHealthStatus added in v1.1.0 

type ResourceHealthStatus string

ResourceHealthStatus The health state of a resource. 

const (
	ResourceHealthStatusDegraded ResourceHealthStatus = "degraded"
	ResourceHealthStatusError    ResourceHealthStatus = "error"
	ResourceHealthStatusHealthy  ResourceHealthStatus = "healthy"
	ResourceHealthStatusUnknown  ResourceHealthStatus = "unknown"
)

Defines values for ResourceHealthStatus.

type ResourceMetadata 

type ResourceMetadata struct {
	// Description The resource description, this optionally augments the name with more context.
	Description *string `json:"description,omitempty"`

	// Name A valid Kubernetes label value, typically used for resource names that can be
	// indexed in the database.
	Name KubernetesLabelValue `json:"name"`

	// Tags A list of tags.
	Tags *TagList `json:"tags,omitempty"`
}

ResourceMetadata Metadata required for all API resource reads and writes.

type ResourceProvisioningStatus 

type ResourceProvisioningStatus string

ResourceProvisioningStatus The provisioning state of a resource. 

const (
	ResourceProvisioningStatusDeprovisioning ResourceProvisioningStatus = "deprovisioning"
	ResourceProvisioningStatusError          ResourceProvisioningStatus = "error"
	ResourceProvisioningStatusPending        ResourceProvisioningStatus = "pending"
	ResourceProvisioningStatusProvisioned    ResourceProvisioningStatus = "provisioned"
	ResourceProvisioningStatusProvisioning   ResourceProvisioningStatus = "provisioning"
	ResourceProvisioningStatusUnknown        ResourceProvisioningStatus = "unknown"
)

Defines values for ResourceProvisioningStatus.

type ResourceReadMetadata 

type ResourceReadMetadata struct {
	// CreatedBy The user who created the resource.
	CreatedBy *string `json:"createdBy,omitempty"`

	// CreationTime The time the resource was created.
	CreationTime time.Time `json:"creationTime"`

	// DeletionTime The time the resource was deleted.
	DeletionTime *time.Time `json:"deletionTime,omitempty"`

	// Description The resource description, this optionally augments the name with more context.
	Description *string `json:"description,omitempty"`

	// HealthStatus The health state of a resource.
	HealthStatus ResourceHealthStatus `json:"healthStatus"`

	// Id The unique resource ID.
	Id string `json:"id"`

	// ModifiedBy The user who updated the resource.
	ModifiedBy *string `json:"modifiedBy,omitempty"`

	// ModifiedTime The time a resource was updated.
	ModifiedTime *time.Time `json:"modifiedTime,omitempty"`

	// Name A valid Kubernetes label value, typically used for resource names that can be
	// indexed in the database.
	Name KubernetesLabelValue `json:"name"`

	// ProvisioningStatus The provisioning state of a resource.
	ProvisioningStatus ResourceProvisioningStatus `json:"provisioningStatus"`

	// Tags A list of tags.
	Tags *TagList `json:"tags,omitempty"`
}

ResourceReadMetadata defines model for resourceReadMetadata.

type ResourceWriteMetadata 

type ResourceWriteMetadata = ResourceMetadata

ResourceWriteMetadata Metadata required for all API resource reads and writes.

type ScopeList added in v1.14.0 

type ScopeList = []string

ScopeList A set of OIDC scopes that are required for authorization.

type Semver 

type Semver = string

Semver A semantic version in the form v1.2.3. Pre-releases and variants are not currently supported.

type StaticResourceMetadata 

type StaticResourceMetadata struct {
	// CreatedBy The user who created the resource.
	CreatedBy *string `json:"createdBy,omitempty"`

	// CreationTime The time the resource was created.
	CreationTime time.Time `json:"creationTime"`

	// Description The resource description, this optionally augments the name with more context.
	Description *string `json:"description,omitempty"`

	// Id The unique resource ID.
	Id string `json:"id"`

	// ModifiedBy The user who updated the resource.
	ModifiedBy *string `json:"modifiedBy,omitempty"`

	// ModifiedTime The time a resource was updated.
	ModifiedTime *time.Time `json:"modifiedTime,omitempty"`

	// Name A valid Kubernetes label value, typically used for resource names that can be
	// indexed in the database.
	Name KubernetesLabelValue `json:"name"`

	// Tags A list of tags.
	Tags *TagList `json:"tags,omitempty"`
}

StaticResourceMetadata defines model for staticResourceMetadata.

type Tag added in v0.1.84 

type Tag struct {
	// Name A unique tag name.
	Name string `json:"name"`

	// Value The value of the tag.
	Value string `json:"value"`
}

Tag A tag mapping arbitrary names to values. These have no special meaning for any component are are intended for use by end users to add additional context to a resource, for example to categorize it.

type TagList added in v0.1.84 

type TagList = []Tag

TagList A list of tags.

type TagSelectorParameter added in v1.4.0 

type TagSelectorParameter = []string

TagSelectorParameter defines model for tagSelectorParameter.

type UnauthorizedResponse 

type UnauthorizedResponse = Error

UnauthorizedResponse Generic error message, compatible with oauth2.

type UnprocessableContentResponse added in v1.13.0 

type UnprocessableContentResponse = Error

UnprocessableContentResponse Generic error message, compatible with oauth2.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.