openapibuilder

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Mar 14, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package openapibuilder provides a fluent builder API for constructing OpenAPI 3.x specifications.

The builder uses a chainable pattern with parent references, allowing natural navigation through the spec structure using Done() methods.

Basic usage: 

spec, err := openapibuilder.NewSpec(openapibuilder.Version310).
    Title("Pet Store API").
    Version("1.0.0").
    Server("https://api.example.com").
    Path("/pets/{petId}").
        Get().
            Summary("Get pet by ID").
            OperationID("getPet").
            Response(200).Description("Success").JSON(RefSchema("Pet")).Done().
        Done().
    Done().
    Build()

The package automatically handles OpenAPI 3.0 vs 3.1 differences such as nullable type representation and examples format.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrMissingTitle       = errors.New("info.title is required")
	ErrMissingVersion     = errors.New("info.version is required")
	ErrMissingDescription = errors.New("response description is required")
	ErrInvalidRef         = errors.New("invalid $ref format")
	ErrEmptyPath          = errors.New("path cannot be empty")
)

Common errors.

Functions

func ToJSON 

func ToJSON(spec *openapi.Spec) ([]byte, error)

ToJSON converts the spec to JSON bytes.

func ToString 

func ToString(spec *openapi.Spec, format openapi.Format) (string, error)

ToString converts the spec to a string in the specified format.

func ToYAML 

func ToYAML(spec *openapi.Spec) ([]byte, error)

ToYAML converts the spec to YAML bytes.

func WriteFile 

func WriteFile(path string, spec *openapi.Spec) error

WriteFile writes the spec to a file. Format is determined by file extension (.json or .yaml/.yml).

func WriteJSON 

func WriteJSON(w io.Writer, spec *openapi.Spec) error

WriteJSON writes the spec as JSON to the given writer.

func WriteYAML 

func WriteYAML(w io.Writer, spec *openapi.Spec) error

WriteYAML writes the spec as YAML to the given writer.

Types

type BuildError 

type BuildError struct {
	Field   string
	Message string
	Err     error
}

BuildError represents an error that occurred during spec building.

func (*BuildError) Error 

func (e *BuildError) Error() string

Error implements the error interface.

func (*BuildError) Unwrap 

func (e *BuildError) Unwrap() error

Unwrap returns the underlying error.

type ComponentsBuilder 

type ComponentsBuilder struct {
	// contains filtered or unexported fields
}

ComponentsBuilder builds an OpenAPI Components object.

func (*ComponentsBuilder) AddSecurityScheme 

func (b *ComponentsBuilder) AddSecurityScheme(name string, scheme *StandaloneSecuritySchemeBuilder) *ComponentsBuilder

AddSecurityScheme adds a pre-built security scheme.

func (*ComponentsBuilder) Build 

func (b *ComponentsBuilder) Build() *openapi.Components

Build returns the constructed components.

func (*ComponentsBuilder) Done 

func (b *ComponentsBuilder) Done() *SpecBuilder

Done returns to the parent SpecBuilder.

func (*ComponentsBuilder) Header 

func (b *ComponentsBuilder) Header(name string, header *HeaderBuilder) *ComponentsBuilder

Header adds a header to the components.

func (*ComponentsBuilder) Parameter 

func (b *ComponentsBuilder) Parameter(name string, param *StandaloneParameterBuilder) *ComponentsBuilder

Parameter adds a parameter to the components.

func (*ComponentsBuilder) RequestBody 

func (b *ComponentsBuilder) RequestBody(name string, body *StandaloneRequestBodyBuilder) *ComponentsBuilder

RequestBody adds a request body to the components.

func (*ComponentsBuilder) Response 

func (b *ComponentsBuilder) Response(name string, response *StandaloneResponseBuilder) *ComponentsBuilder

Response adds a response to the components.

func (*ComponentsBuilder) Schema 

func (b *ComponentsBuilder) Schema(name string, schema *SchemaBuilder) *ComponentsBuilder

Schema adds a schema to the components.

func (*ComponentsBuilder) SecurityScheme 

func (b *ComponentsBuilder) SecurityScheme(name string) *SecuritySchemeBuilder

SecurityScheme starts building a security scheme.

type HeaderBuilder 

type HeaderBuilder struct {
	// contains filtered or unexported fields
}

HeaderBuilder builds an OpenAPI Header object.

func (*HeaderBuilder) Build 

func (b *HeaderBuilder) Build() *openapi.Header

Build returns the constructed header.

func (*HeaderBuilder) Description 

func (b *HeaderBuilder) Description(d string) *HeaderBuilder

Description sets the header description.

func (*HeaderBuilder) Done 

func (b *HeaderBuilder) Done() *ResponseBuilder

Done returns to the parent ResponseBuilder.

func (*HeaderBuilder) Format 

func (b *HeaderBuilder) Format(f string) *HeaderBuilder

Format sets the header format.

func (*HeaderBuilder) Required 

func (b *HeaderBuilder) Required() *HeaderBuilder

Required marks the header as required.

func (*HeaderBuilder) Schema 

func (b *HeaderBuilder) Schema(schema *SchemaBuilder) *HeaderBuilder

Schema sets the header schema.

func (*HeaderBuilder) Type 

func (b *HeaderBuilder) Type(t string) *HeaderBuilder

Type sets the header type (creates a simple schema).

type OAuthFlowBuilder 

type OAuthFlowBuilder struct {
	// contains filtered or unexported fields
}

OAuthFlowBuilder builds a single OAuth2 flow.

func (*OAuthFlowBuilder) Done 

func (b *OAuthFlowBuilder) Done() *OAuthFlowsBuilder

Done returns to the parent OAuthFlowsBuilder.

func (*OAuthFlowBuilder) RefreshURL 

func (b *OAuthFlowBuilder) RefreshURL(url string) *OAuthFlowBuilder

RefreshURL sets the refresh URL.

func (*OAuthFlowBuilder) Scope 

func (b *OAuthFlowBuilder) Scope(name, description string) *OAuthFlowBuilder

Scope adds a scope to the flow.

func (*OAuthFlowBuilder) Scopes 

func (b *OAuthFlowBuilder) Scopes(scopes map[string]string) *OAuthFlowBuilder

Scopes adds multiple scopes to the flow.

type OAuthFlowsBuilder 

type OAuthFlowsBuilder struct {
	// contains filtered or unexported fields
}

OAuthFlowsBuilder builds OAuth2 flows.

func (*OAuthFlowsBuilder) AuthorizationCode 

func (b *OAuthFlowsBuilder) AuthorizationCode(authURL, tokenURL string) *OAuthFlowBuilder

AuthorizationCode configures the authorization code flow.

func (*OAuthFlowsBuilder) ClientCredentials 

func (b *OAuthFlowsBuilder) ClientCredentials(tokenURL string) *OAuthFlowBuilder

ClientCredentials configures the client credentials flow.

func (*OAuthFlowsBuilder) Done 

func (b *OAuthFlowsBuilder) Done() *SecuritySchemeBuilder

Done returns to the parent SecuritySchemeBuilder.

func (*OAuthFlowsBuilder) Implicit 

func (b *OAuthFlowsBuilder) Implicit(authURL string) *OAuthFlowBuilder

Implicit configures the implicit flow.

func (*OAuthFlowsBuilder) Password 

func (b *OAuthFlowsBuilder) Password(tokenURL string) *OAuthFlowBuilder

Password configures the password flow.

type OperationBuilder 

type OperationBuilder struct {
	// contains filtered or unexported fields
}

OperationBuilder builds an OpenAPI Operation object.

func (*OperationBuilder) Build 

func (b *OperationBuilder) Build() *openapi.Operation

Build returns the constructed operation.

func (*OperationBuilder) CookieParam 

func (b *OperationBuilder) CookieParam(name string) *ParameterBuilder

CookieParam adds a cookie parameter to the operation.

func (*OperationBuilder) Deprecated 

func (b *OperationBuilder) Deprecated() *OperationBuilder

Deprecated marks the operation as deprecated.

func (*OperationBuilder) Description 

func (b *OperationBuilder) Description(d string) *OperationBuilder

Description sets the operation description.

func (*OperationBuilder) Done 

func (b *OperationBuilder) Done() *PathItemBuilder

Done returns to the parent PathItemBuilder.

func (*OperationBuilder) HeaderParam 

func (b *OperationBuilder) HeaderParam(name string) *ParameterBuilder

HeaderParam adds a header parameter to the operation.

func (*OperationBuilder) JSONBody 

func (b *OperationBuilder) JSONBody(schema *SchemaBuilder) *OperationBuilder

JSONBody is a shortcut for a required JSON request body.

func (*OperationBuilder) NoSecurity 

func (b *OperationBuilder) NoSecurity() *OperationBuilder

NoSecurity explicitly removes security requirements (empty array).

func (*OperationBuilder) OperationID 

func (b *OperationBuilder) OperationID(id string) *OperationBuilder

OperationID sets the operation ID.

func (*OperationBuilder) Parameter 

func (b *OperationBuilder) Parameter(param *openapi.Parameter) *OperationBuilder

Parameter adds a pre-built parameter to the operation.

func (*OperationBuilder) PathParam 

func (b *OperationBuilder) PathParam(name string) *ParameterBuilder

PathParam adds a path parameter to the operation.

func (*OperationBuilder) QueryParam 

func (b *OperationBuilder) QueryParam(name string) *ParameterBuilder

QueryParam adds a query parameter to the operation.

func (*OperationBuilder) RequestBody 

func (b *OperationBuilder) RequestBody() *RequestBodyBuilder

RequestBody starts building a request body.

func (*OperationBuilder) Response 

func (b *OperationBuilder) Response(statusCode int) *ResponseBuilder

Response adds a response for the given status code.

func (*OperationBuilder) Response2XX 

func (b *OperationBuilder) Response2XX() *ResponseBuilder

Response2XX adds a 2XX response.

func (*OperationBuilder) Response4XX 

func (b *OperationBuilder) Response4XX() *ResponseBuilder

Response4XX adds a 4XX response.

func (*OperationBuilder) Response5XX 

func (b *OperationBuilder) Response5XX() *ResponseBuilder

Response5XX adds a 5XX response.

func (*OperationBuilder) ResponseDefault 

func (b *OperationBuilder) ResponseDefault() *ResponseBuilder

ResponseDefault adds a default response.

func (*OperationBuilder) Security 

func (b *OperationBuilder) Security(name string, scopes ...string) *OperationBuilder

Security adds a security requirement.

func (*OperationBuilder) Summary 

func (b *OperationBuilder) Summary(s string) *OperationBuilder

Summary sets the operation summary.

func (*OperationBuilder) Tags 

func (b *OperationBuilder) Tags(tags ...string) *OperationBuilder

Tags adds tags to the operation.

type ParameterBuilder 

type ParameterBuilder struct {
	// contains filtered or unexported fields
}

ParameterBuilder builds an OpenAPI Parameter object.

func (*ParameterBuilder) AllowEmptyValue 

func (b *ParameterBuilder) AllowEmptyValue() *ParameterBuilder

AllowEmptyValue allows empty values for the parameter.

func (*ParameterBuilder) Build 

func (b *ParameterBuilder) Build() *openapi.Parameter

Build returns the constructed parameter.

func (*ParameterBuilder) Deprecated 

func (b *ParameterBuilder) Deprecated() *ParameterBuilder

Deprecated marks the parameter as deprecated.

func (*ParameterBuilder) Description 

func (b *ParameterBuilder) Description(d string) *ParameterBuilder

Description sets the parameter description.

func (*ParameterBuilder) DoneOp 

func (b *ParameterBuilder) DoneOp() *OperationBuilder

DoneOp returns to the parent OperationBuilder.

func (*ParameterBuilder) Enum 

func (b *ParameterBuilder) Enum(values ...any) *ParameterBuilder

Enum sets the allowed values.

func (*ParameterBuilder) Example 

func (b *ParameterBuilder) Example(v any) *ParameterBuilder

Example sets an example value for the parameter.

func (*ParameterBuilder) Format 

func (b *ParameterBuilder) Format(f string) *ParameterBuilder

Format sets the parameter format.

func (*ParameterBuilder) Required 

func (b *ParameterBuilder) Required() *ParameterBuilder

Required marks the parameter as required.

func (*ParameterBuilder) Schema 

func (b *ParameterBuilder) Schema(schema *SchemaBuilder) *ParameterBuilder

Schema sets the parameter schema.

func (*ParameterBuilder) Type 

func (b *ParameterBuilder) Type(t string) *ParameterBuilder

Type sets the parameter type (creates a simple schema).

type PathItemBuilder 

type PathItemBuilder struct {
	// contains filtered or unexported fields
}

PathItemBuilder builds an OpenAPI PathItem object.

func (*PathItemBuilder) Build 

func (b *PathItemBuilder) Build() *openapi.PathItem

Build returns the constructed path item.

func (*PathItemBuilder) Delete 

func (b *PathItemBuilder) Delete() *OperationBuilder

Delete starts building a DELETE operation.

func (*PathItemBuilder) Description 

func (b *PathItemBuilder) Description(d string) *PathItemBuilder

Description sets the path item description.

func (*PathItemBuilder) Done 

func (b *PathItemBuilder) Done() *SpecBuilder

Done returns to the parent SpecBuilder.

func (*PathItemBuilder) Get 

func (b *PathItemBuilder) Get() *OperationBuilder

Get starts building a GET operation.

func (*PathItemBuilder) Head 

func (b *PathItemBuilder) Head() *OperationBuilder

Head starts building a HEAD operation.

func (*PathItemBuilder) Options 

func (b *PathItemBuilder) Options() *OperationBuilder

Options starts building an OPTIONS operation.

func (*PathItemBuilder) Parameter 

func (b *PathItemBuilder) Parameter(param *openapi.Parameter) *PathItemBuilder

Parameter adds a shared parameter to the path item.

func (*PathItemBuilder) Patch 

func (b *PathItemBuilder) Patch() *OperationBuilder

Patch starts building a PATCH operation.

func (*PathItemBuilder) Post 

func (b *PathItemBuilder) Post() *OperationBuilder

Post starts building a POST operation.

func (*PathItemBuilder) Put 

func (b *PathItemBuilder) Put() *OperationBuilder

Put starts building a PUT operation.

func (*PathItemBuilder) Summary 

func (b *PathItemBuilder) Summary(s string) *PathItemBuilder

Summary sets the path item summary.

func (*PathItemBuilder) Trace 

func (b *PathItemBuilder) Trace() *OperationBuilder

Trace starts building a TRACE operation.

type RequestBodyBuilder 

type RequestBodyBuilder struct {
	// contains filtered or unexported fields
}

RequestBodyBuilder builds an OpenAPI RequestBody object.

func (*RequestBodyBuilder) Build 

func (b *RequestBodyBuilder) Build() *openapi.RequestBody

Build returns the constructed request body.

func (*RequestBodyBuilder) Content 

func (b *RequestBodyBuilder) Content(mediaType string, schema *SchemaBuilder) *RequestBodyBuilder

Content adds a media type to the request body.

func (*RequestBodyBuilder) Description 

func (b *RequestBodyBuilder) Description(d string) *RequestBodyBuilder

Description sets the request body description.

func (*RequestBodyBuilder) Done 

func (b *RequestBodyBuilder) Done() *OperationBuilder

Done returns to the parent OperationBuilder.

func (*RequestBodyBuilder) FormURLEncoded 

func (b *RequestBodyBuilder) FormURLEncoded(schema *SchemaBuilder) *RequestBodyBuilder

FormURLEncoded adds application/x-www-form-urlencoded content.

func (*RequestBodyBuilder) JSON 

func (b *RequestBodyBuilder) JSON(schema *SchemaBuilder) *RequestBodyBuilder

JSON adds application/json content.

func (*RequestBodyBuilder) MultipartFormData 

func (b *RequestBodyBuilder) MultipartFormData(schema *SchemaBuilder) *RequestBodyBuilder

MultipartFormData adds multipart/form-data content.

func (*RequestBodyBuilder) OctetStream 

func (b *RequestBodyBuilder) OctetStream(schema *SchemaBuilder) *RequestBodyBuilder

OctetStream adds application/octet-stream content.

func (*RequestBodyBuilder) Required 

func (b *RequestBodyBuilder) Required() *RequestBodyBuilder

Required marks the request body as required.

func (*RequestBodyBuilder) TextPlain 

func (b *RequestBodyBuilder) TextPlain(schema *SchemaBuilder) *RequestBodyBuilder

TextPlain adds text/plain content.

func (*RequestBodyBuilder) WithExample 

func (b *RequestBodyBuilder) WithExample(example any) *RequestBodyBuilder

WithExample adds an example to the most recently added content type.

func (*RequestBodyBuilder) XML 

func (b *RequestBodyBuilder) XML(schema *SchemaBuilder) *RequestBodyBuilder

XML adds application/xml content.

type ResponseBuilder 

type ResponseBuilder struct {
	// contains filtered or unexported fields
}

ResponseBuilder builds an OpenAPI Response object.

func (*ResponseBuilder) Build 

func (b *ResponseBuilder) Build() *openapi.Response

Build returns the constructed response.

func (*ResponseBuilder) Content 

func (b *ResponseBuilder) Content(mediaType string, schema *SchemaBuilder) *ResponseBuilder

Content adds a media type to the response.

func (*ResponseBuilder) Description 

func (b *ResponseBuilder) Description(d string) *ResponseBuilder

Description sets the response description (required).

func (*ResponseBuilder) Done 

func (b *ResponseBuilder) Done() *OperationBuilder

Done returns to the parent OperationBuilder.

func (*ResponseBuilder) HTML 

func (b *ResponseBuilder) HTML(schema *SchemaBuilder) *ResponseBuilder

HTML adds text/html content.

func (*ResponseBuilder) Header 

func (b *ResponseBuilder) Header(name string) *HeaderBuilder

Header adds a header to the response.

func (*ResponseBuilder) JSON 

func (b *ResponseBuilder) JSON(schema *SchemaBuilder) *ResponseBuilder

JSON adds application/json content.

func (*ResponseBuilder) OctetStream 

func (b *ResponseBuilder) OctetStream(schema *SchemaBuilder) *ResponseBuilder

OctetStream adds application/octet-stream content.

func (*ResponseBuilder) TextPlain 

func (b *ResponseBuilder) TextPlain(schema *SchemaBuilder) *ResponseBuilder

TextPlain adds text/plain content.

func (*ResponseBuilder) XML 

func (b *ResponseBuilder) XML(schema *SchemaBuilder) *ResponseBuilder

XML adds application/xml content.

type SchemaBuilder 

type SchemaBuilder struct {
	// contains filtered or unexported fields
}

SchemaBuilder builds an OpenAPI Schema object.

func ArraySchema 

func ArraySchema(items *SchemaBuilder) *SchemaBuilder

ArraySchema creates a new array schema builder with the given items schema.

func BooleanSchema 

func BooleanSchema() *SchemaBuilder

BooleanSchema creates a new boolean schema builder.

func IntegerSchema 

func IntegerSchema() *SchemaBuilder

IntegerSchema creates a new integer schema builder.

func NewSchema 

func NewSchema() *SchemaBuilder

NewSchema creates an empty schema builder.

func NumberSchema 

func NumberSchema() *SchemaBuilder

NumberSchema creates a new number schema builder.

func ObjectSchema 

func ObjectSchema() *SchemaBuilder

ObjectSchema creates a new object schema builder.

func Ref 

func Ref(ref string) *SchemaBuilder

Ref creates an explicit schema reference.

func RefSchema 

func RefSchema(name string) *SchemaBuilder

RefSchema creates a schema reference to a component schema. The name is automatically prefixed with #/components/schemas/.

func StringSchema 

func StringSchema() *SchemaBuilder

StringSchema creates a new string schema builder.

func (*SchemaBuilder) AdditionalProperties 

func (b *SchemaBuilder) AdditionalProperties(schema *SchemaBuilder) *SchemaBuilder

AdditionalProperties sets the additionalProperties schema. Pass nil to disallow additional properties (false). Pass a SchemaBuilder to allow additional properties of that type.

func (*SchemaBuilder) AdditionalPropertiesAllowed 

func (b *SchemaBuilder) AdditionalPropertiesAllowed() *SchemaBuilder

AdditionalPropertiesAllowed allows any additional properties.

func (*SchemaBuilder) AllOf 

func (b *SchemaBuilder) AllOf(schemas ...*SchemaBuilder) *SchemaBuilder

AllOf adds schemas to the allOf composition.

func (*SchemaBuilder) AnyOf 

func (b *SchemaBuilder) AnyOf(schemas ...*SchemaBuilder) *SchemaBuilder

AnyOf adds schemas to the anyOf composition.

func (*SchemaBuilder) Build 

func (b *SchemaBuilder) Build() *openapi.Schema

Build returns the constructed schema.

func (*SchemaBuilder) Const 

func (b *SchemaBuilder) Const(v any) *SchemaBuilder

Const sets the const value.

func (*SchemaBuilder) Default 

func (b *SchemaBuilder) Default(v any) *SchemaBuilder

Default sets the default value.

func (*SchemaBuilder) Deprecated 

func (b *SchemaBuilder) Deprecated() *SchemaBuilder

Deprecated marks the schema as deprecated.

func (*SchemaBuilder) Description 

func (b *SchemaBuilder) Description(d string) *SchemaBuilder

Description sets the schema description.

func (*SchemaBuilder) Enum 

func (b *SchemaBuilder) Enum(values ...any) *SchemaBuilder

Enum sets the allowed values.

func (*SchemaBuilder) Examples 

func (b *SchemaBuilder) Examples(examples ...any) *SchemaBuilder

Examples adds examples (OpenAPI 3.1).

func (*SchemaBuilder) ExclusiveMaximum 

func (b *SchemaBuilder) ExclusiveMaximum(v float64) *SchemaBuilder

ExclusiveMaximum sets the exclusive maximum value.

func (*SchemaBuilder) ExclusiveMinimum 

func (b *SchemaBuilder) ExclusiveMinimum(v float64) *SchemaBuilder

ExclusiveMinimum sets the exclusive minimum value.

func (*SchemaBuilder) Format 

func (b *SchemaBuilder) Format(f string) *SchemaBuilder

Format sets the schema format.

func (*SchemaBuilder) Items 

func (b *SchemaBuilder) Items(items *SchemaBuilder) *SchemaBuilder

Items sets the items schema for arrays.

func (*SchemaBuilder) MaxItems 

func (b *SchemaBuilder) MaxItems(v int) *SchemaBuilder

MaxItems sets the maximum array length.

func (*SchemaBuilder) MaxLength 

func (b *SchemaBuilder) MaxLength(v int) *SchemaBuilder

MaxLength sets the maximum string length.

func (*SchemaBuilder) MaxProperties 

func (b *SchemaBuilder) MaxProperties(v int) *SchemaBuilder

MaxProperties sets the maximum number of properties.

func (*SchemaBuilder) Maximum 

func (b *SchemaBuilder) Maximum(v float64) *SchemaBuilder

Maximum sets the maximum value.

func (*SchemaBuilder) MinItems 

func (b *SchemaBuilder) MinItems(v int) *SchemaBuilder

MinItems sets the minimum array length.

func (*SchemaBuilder) MinLength 

func (b *SchemaBuilder) MinLength(v int) *SchemaBuilder

MinLength sets the minimum string length.

func (*SchemaBuilder) MinProperties 

func (b *SchemaBuilder) MinProperties(v int) *SchemaBuilder

MinProperties sets the minimum number of properties.

func (*SchemaBuilder) Minimum 

func (b *SchemaBuilder) Minimum(v float64) *SchemaBuilder

Minimum sets the minimum value.

func (*SchemaBuilder) MultipleOf 

func (b *SchemaBuilder) MultipleOf(v float64) *SchemaBuilder

MultipleOf sets the multipleOf constraint.

func (*SchemaBuilder) Not 

func (b *SchemaBuilder) Not(schema *SchemaBuilder) *SchemaBuilder

Not sets the not schema.

func (*SchemaBuilder) Nullable 

func (b *SchemaBuilder) Nullable() *SchemaBuilder

Nullable marks the schema as nullable. For OpenAPI 3.1+, this adds "null" to the type array. For OpenAPI 3.0, this sets the nullable keyword.

func (*SchemaBuilder) OneOf 

func (b *SchemaBuilder) OneOf(schemas ...*SchemaBuilder) *SchemaBuilder

OneOf adds schemas to the oneOf composition.

func (*SchemaBuilder) Pattern 

func (b *SchemaBuilder) Pattern(p string) *SchemaBuilder

Pattern sets the regex pattern for strings.

func (*SchemaBuilder) Property 

func (b *SchemaBuilder) Property(name string, schema *SchemaBuilder) *SchemaBuilder

Property adds a property to an object schema.

func (*SchemaBuilder) ReadOnly 

func (b *SchemaBuilder) ReadOnly() *SchemaBuilder

ReadOnly marks the schema as read-only.

func (*SchemaBuilder) Required 

func (b *SchemaBuilder) Required(names ...string) *SchemaBuilder

Required marks properties as required.

func (*SchemaBuilder) Title 

func (b *SchemaBuilder) Title(t string) *SchemaBuilder

Title sets the schema title.

func (*SchemaBuilder) Type 

func (b *SchemaBuilder) Type(t string) *SchemaBuilder

Type sets the schema type.

func (*SchemaBuilder) UniqueItems 

func (b *SchemaBuilder) UniqueItems() *SchemaBuilder

UniqueItems requires array items to be unique.

func (*SchemaBuilder) WithVersion 

func (b *SchemaBuilder) WithVersion(v Version) *SchemaBuilder

WithVersion sets the OpenAPI version for version-aware behavior.

func (*SchemaBuilder) WriteOnly 

func (b *SchemaBuilder) WriteOnly() *SchemaBuilder

WriteOnly marks the schema as write-only.

type SecuritySchemeBuilder 

type SecuritySchemeBuilder struct {
	// contains filtered or unexported fields
}

SecuritySchemeBuilder builds an OpenAPI SecurityScheme object.

func (*SecuritySchemeBuilder) APIKeyCookie 

func (b *SecuritySchemeBuilder) APIKeyCookie(cookieName string) *SecuritySchemeBuilder

APIKeyCookie configures API key authentication via cookie.

func (*SecuritySchemeBuilder) APIKeyHeader 

func (b *SecuritySchemeBuilder) APIKeyHeader(headerName string) *SecuritySchemeBuilder

APIKeyHeader configures API key authentication via header.

func (*SecuritySchemeBuilder) APIKeyQuery 

func (b *SecuritySchemeBuilder) APIKeyQuery(paramName string) *SecuritySchemeBuilder

APIKeyQuery configures API key authentication via query parameter.

func (*SecuritySchemeBuilder) BasicAuth 

func (b *SecuritySchemeBuilder) BasicAuth() *SecuritySchemeBuilder

BasicAuth configures HTTP Basic authentication.

func (*SecuritySchemeBuilder) BearerAuth 

func (b *SecuritySchemeBuilder) BearerAuth() *SecuritySchemeBuilder

BearerAuth configures HTTP Bearer authentication.

func (*SecuritySchemeBuilder) BearerFormat 

func (b *SecuritySchemeBuilder) BearerFormat(format string) *SecuritySchemeBuilder

BearerFormat sets the bearer format (e.g., "JWT").

func (*SecuritySchemeBuilder) Build 

func (b *SecuritySchemeBuilder) Build() *openapi.SecurityScheme

Build returns the constructed security scheme.

func (*SecuritySchemeBuilder) Description 

func (b *SecuritySchemeBuilder) Description(d string) *SecuritySchemeBuilder

Description sets the security scheme description.

func (*SecuritySchemeBuilder) Done 

func (b *SecuritySchemeBuilder) Done() *ComponentsBuilder

Done returns to the parent ComponentsBuilder.

func (*SecuritySchemeBuilder) OAuth2 

func (b *SecuritySchemeBuilder) OAuth2() *OAuthFlowsBuilder

OAuth2 starts configuring OAuth2 authentication.

func (*SecuritySchemeBuilder) OpenIDConnect 

func (b *SecuritySchemeBuilder) OpenIDConnect(url string) *SecuritySchemeBuilder

OpenIDConnect configures OpenID Connect authentication.

type ServerBuilder 

type ServerBuilder struct {
	// contains filtered or unexported fields
}

ServerBuilder builds an OpenAPI Server object.

func (*ServerBuilder) Build 

func (b *ServerBuilder) Build() *openapi.Server

Build returns the constructed server.

func (*ServerBuilder) Description 

func (b *ServerBuilder) Description(d string) *ServerBuilder

Description sets the server description.

func (*ServerBuilder) Done 

func (b *ServerBuilder) Done() *SpecBuilder

Done returns to the parent SpecBuilder.

type SpecBuilder 

type SpecBuilder struct {
	// contains filtered or unexported fields
}

SpecBuilder builds an OpenAPI Specification.

func NewSpec 

func NewSpec(version Version) *SpecBuilder

NewSpec creates a new spec builder with the given OpenAPI version.

func (*SpecBuilder) AddPath 

func (b *SpecBuilder) AddPath(path string, pathItem *openapi.PathItem) *SpecBuilder

AddPath adds a pre-built path item.

func (*SpecBuilder) Build 

func (b *SpecBuilder) Build() (*openapi.Spec, error)

Build validates and returns the constructed spec.

func (*SpecBuilder) BuildUnchecked 

func (b *SpecBuilder) BuildUnchecked() *openapi.Spec

BuildUnchecked returns the spec without validation.

func (*SpecBuilder) Components 

func (b *SpecBuilder) Components() *ComponentsBuilder

Components starts building the components section.

func (*SpecBuilder) Contact 

func (b *SpecBuilder) Contact(name, url, email string) *SpecBuilder

Contact sets the contact information.

func (*SpecBuilder) Description 

func (b *SpecBuilder) Description(desc string) *SpecBuilder

Description sets the API description.

func (*SpecBuilder) GetVersion 

func (b *SpecBuilder) GetVersion() Version

GetVersion returns the OpenAPI version.

func (*SpecBuilder) License 

func (b *SpecBuilder) License(name, url string) *SpecBuilder

License sets the license information.

func (*SpecBuilder) MustBuild 

func (b *SpecBuilder) MustBuild() *openapi.Spec

MustBuild builds the spec and panics on error.

func (*SpecBuilder) Path 

func (b *SpecBuilder) Path(path string) *PathItemBuilder

Path starts building a path item.

func (*SpecBuilder) Security 

func (b *SpecBuilder) Security(name string, scopes ...string) *SpecBuilder

Security adds a global security requirement.

func (*SpecBuilder) Server 

func (b *SpecBuilder) Server(url string) *SpecBuilder

Server adds a server with a simple URL.

func (*SpecBuilder) ServerBuilder 

func (b *SpecBuilder) ServerBuilder(url string) *ServerBuilder

ServerBuilder starts building a server with more options.

func (*SpecBuilder) ServerWithDescription 

func (b *SpecBuilder) ServerWithDescription(url, description string) *SpecBuilder

ServerWithDescription adds a server with a URL and description.

func (*SpecBuilder) Spec 

func (b *SpecBuilder) Spec() *openapi.Spec

Spec returns the underlying spec (for advanced use).

func (*SpecBuilder) Title 

func (b *SpecBuilder) Title(title string) *SpecBuilder

Title sets the API title.

func (*SpecBuilder) Version 

func (b *SpecBuilder) Version(v string) *SpecBuilder

Version sets the API version.

type StandaloneParameterBuilder 

type StandaloneParameterBuilder struct {
	// contains filtered or unexported fields
}

StandaloneParameterBuilder builds parameters without a parent operation.

func CookieParam 

func CookieParam(name string) *StandaloneParameterBuilder

CookieParam creates a cookie parameter builder (standalone).

func HeaderParam 

func HeaderParam(name string) *StandaloneParameterBuilder

HeaderParam creates a header parameter builder (standalone).

func PathParam 

func PathParam(name string) *StandaloneParameterBuilder

PathParam creates a path parameter builder (standalone).

func QueryParam 

func QueryParam(name string) *StandaloneParameterBuilder

QueryParam creates a query parameter builder (standalone).

func (*StandaloneParameterBuilder) AllowEmptyValue 

func (b *StandaloneParameterBuilder) AllowEmptyValue() *StandaloneParameterBuilder

AllowEmptyValue allows empty values for the parameter.

func (*StandaloneParameterBuilder) Build 

func (b *StandaloneParameterBuilder) Build() *openapi.Parameter

Build returns the constructed parameter.

func (*StandaloneParameterBuilder) Deprecated 

func (b *StandaloneParameterBuilder) Deprecated() *StandaloneParameterBuilder

Deprecated marks the parameter as deprecated.

func (*StandaloneParameterBuilder) Description 

func (b *StandaloneParameterBuilder) Description(d string) *StandaloneParameterBuilder

Description sets the parameter description.

func (*StandaloneParameterBuilder) Enum 

func (b *StandaloneParameterBuilder) Enum(values ...any) *StandaloneParameterBuilder

Enum sets the allowed values.

func (*StandaloneParameterBuilder) Example 

func (b *StandaloneParameterBuilder) Example(v any) *StandaloneParameterBuilder

Example sets an example value for the parameter.

func (*StandaloneParameterBuilder) Format 

func (b *StandaloneParameterBuilder) Format(f string) *StandaloneParameterBuilder

Format sets the parameter format.

func (*StandaloneParameterBuilder) Required 

func (b *StandaloneParameterBuilder) Required() *StandaloneParameterBuilder

Required marks the parameter as required.

func (*StandaloneParameterBuilder) Schema 

func (b *StandaloneParameterBuilder) Schema(schema *SchemaBuilder) *StandaloneParameterBuilder

Schema sets the parameter schema.

func (*StandaloneParameterBuilder) Type 

func (b *StandaloneParameterBuilder) Type(t string) *StandaloneParameterBuilder

Type sets the parameter type (creates a simple schema).

type StandaloneRequestBodyBuilder 

type StandaloneRequestBodyBuilder struct {
	// contains filtered or unexported fields
}

StandaloneRequestBodyBuilder builds request bodies without a parent.

func NewRequestBody 

func NewRequestBody() *StandaloneRequestBodyBuilder

NewRequestBody creates a standalone request body builder.

func (*StandaloneRequestBodyBuilder) Build 

func (b *StandaloneRequestBodyBuilder) Build() *openapi.RequestBody

Build returns the constructed request body.

func (*StandaloneRequestBodyBuilder) Content 

func (b *StandaloneRequestBodyBuilder) Content(mediaType string, schema *SchemaBuilder) *StandaloneRequestBodyBuilder

Content adds a media type to the request body.

func (*StandaloneRequestBodyBuilder) Description 

func (b *StandaloneRequestBodyBuilder) Description(d string) *StandaloneRequestBodyBuilder

Description sets the request body description.

func (*StandaloneRequestBodyBuilder) JSON 

func (b *StandaloneRequestBodyBuilder) JSON(schema *SchemaBuilder) *StandaloneRequestBodyBuilder

JSON adds application/json content.

func (*StandaloneRequestBodyBuilder) Required 

func (b *StandaloneRequestBodyBuilder) Required() *StandaloneRequestBodyBuilder

Required marks the request body as required.

type StandaloneResponseBuilder 

type StandaloneResponseBuilder struct {
	// contains filtered or unexported fields
}

StandaloneResponseBuilder builds responses without a parent.

func NewResponse 

func NewResponse() *StandaloneResponseBuilder

NewResponse creates a standalone response builder.

func (*StandaloneResponseBuilder) Build 

func (b *StandaloneResponseBuilder) Build() *openapi.Response

Build returns the constructed response.

func (*StandaloneResponseBuilder) Content 

func (b *StandaloneResponseBuilder) Content(mediaType string, schema *SchemaBuilder) *StandaloneResponseBuilder

Content adds a media type to the response.

func (*StandaloneResponseBuilder) Description 

func (b *StandaloneResponseBuilder) Description(d string) *StandaloneResponseBuilder

Description sets the response description (required).

func (*StandaloneResponseBuilder) JSON 

func (b *StandaloneResponseBuilder) JSON(schema *SchemaBuilder) *StandaloneResponseBuilder

JSON adds application/json content.

type StandaloneSecuritySchemeBuilder 

type StandaloneSecuritySchemeBuilder struct {
	// contains filtered or unexported fields
}

StandaloneSecuritySchemeBuilder builds security schemes without a parent.

func NewSecurityScheme 

func NewSecurityScheme() *StandaloneSecuritySchemeBuilder

NewSecurityScheme creates a standalone security scheme builder.

func (*StandaloneSecuritySchemeBuilder) APIKeyHeader 

func (b *StandaloneSecuritySchemeBuilder) APIKeyHeader(headerName string) *StandaloneSecuritySchemeBuilder

APIKeyHeader configures API key authentication via header.

func (*StandaloneSecuritySchemeBuilder) BasicAuth 

func (b *StandaloneSecuritySchemeBuilder) BasicAuth() *StandaloneSecuritySchemeBuilder

BasicAuth configures HTTP Basic authentication.

func (*StandaloneSecuritySchemeBuilder) BearerAuth 

func (b *StandaloneSecuritySchemeBuilder) BearerAuth() *StandaloneSecuritySchemeBuilder

BearerAuth configures HTTP Bearer authentication.

func (*StandaloneSecuritySchemeBuilder) BearerFormat 

func (b *StandaloneSecuritySchemeBuilder) BearerFormat(format string) *StandaloneSecuritySchemeBuilder

BearerFormat sets the bearer format (e.g., "JWT").

func (*StandaloneSecuritySchemeBuilder) Build 

func (b *StandaloneSecuritySchemeBuilder) Build() *openapi.SecurityScheme

Build returns the constructed security scheme.

func (*StandaloneSecuritySchemeBuilder) Description 

func (b *StandaloneSecuritySchemeBuilder) Description(d string) *StandaloneSecuritySchemeBuilder

Description sets the security scheme description.

type StandaloneServerBuilder 

type StandaloneServerBuilder struct {
	// contains filtered or unexported fields
}

StandaloneServerBuilder builds servers without a parent.

func NewServer 

func NewServer(url string) *StandaloneServerBuilder

NewServer creates a standalone server builder.

func (*StandaloneServerBuilder) Build 

func (b *StandaloneServerBuilder) Build() *openapi.Server

Build returns the constructed server.

func (*StandaloneServerBuilder) Description 

func (b *StandaloneServerBuilder) Description(d string) *StandaloneServerBuilder

Description sets the server description.

type ValidationErrors 

type ValidationErrors struct {
	Errors []error
}

ValidationErrors collects multiple validation errors.

func (*ValidationErrors) Add 

func (e *ValidationErrors) Add(err error)

Add adds an error to the collection.

func (*ValidationErrors) AddField 

func (e *ValidationErrors) AddField(field, message string)

AddField adds a field-specific error.

func (*ValidationErrors) Error 

func (e *ValidationErrors) Error() string

Error implements the error interface.

func (*ValidationErrors) ErrorOrNil 

func (e *ValidationErrors) ErrorOrNil() error

ErrorOrNil returns the error if there are any, or nil.

func (*ValidationErrors) HasErrors 

func (e *ValidationErrors) HasErrors() bool

HasErrors returns true if there are any errors.

type Version 

type Version string

Version represents an OpenAPI specification version. 

const (
	// OpenAPI 3.0.x versions
	Version300 Version = "3.0.0"
	Version301 Version = "3.0.1"
	Version302 Version = "3.0.2"
	Version303 Version = "3.0.3"

	// OpenAPI 3.1.x versions
	Version310 Version = "3.1.0"
	Version311 Version = "3.1.1"

	// OpenAPI 3.2.x versions (draft/upcoming)
	Version320 Version = "3.2.0"
)

Supported OpenAPI versions.

func (Version) Is3x 

func (v Version) Is3x() bool

Is3x returns true if this is an OpenAPI 3.x version.

func (Version) Is30x 

func (v Version) Is30x() bool

Is30x returns true if this is an OpenAPI 3.0.x version.

func (Version) Is31x 

func (v Version) Is31x() bool

Is31x returns true if this is an OpenAPI 3.1.x version.

func (Version) Is32x 

func (v Version) Is32x() bool

Is32x returns true if this is an OpenAPI 3.2.x version.

func (Version) String 

func (v Version) String() string

String returns the version string.

Source Files

View all Source files

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.