openapi

package
v1.29.0 Latest Latest
Warning

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

 Go to latest Published: Sep 14, 2026 License: Apache-2.0 Imports: 4 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Handler 

func Handler(provider DocumentProvider) http.Handler

Handler builds an http.Handler that serves the document as JSON.

func HandlerFunc 

func HandlerFunc(provider DocumentProvider) http.HandlerFunc

HandlerFunc adapts a provider into a GET-friendly handler func.

func JSONContent 

func JSONContent(schema Schema) map[string]MediaType

func Marshal 

func Marshal(doc *Document) ([]byte, error)

func PublicSecurity 

func PublicSecurity() *[]SecurityRequirement

PublicSecurity returns an explicit empty security override marking an operation as requiring NO authentication, even when the document declares a global security requirement. (A nil Operation.Security inherits the global.) This is a contract DECLARATION only — runtime auth enforcement is the app middleware's responsibility, never the document's.

func RequireSecurity 

func RequireSecurity(reqs ...SecurityRequirement) *[]SecurityRequirement

RequireSecurity wraps requirements into the pointer form an Operation's Security field takes; a non-nil value overrides the document's global security for that operation.

func WriteJSON 

func WriteJSON(w io.Writer, doc *Document) error

Types

type Components 

type Components struct {
	Schemas         map[string]Schema         `json:"schemas,omitempty"`
	SecuritySchemes map[string]SecurityScheme `json:"securitySchemes,omitempty"`
}

type Document 

type Document struct {
	OpenAPI    string                `json:"openapi"`
	Info       Info                  `json:"info"`
	Servers    []Server              `json:"servers,omitempty"`
	Security   []SecurityRequirement `json:"security,omitempty"`
	Paths      map[string]PathItem   `json:"paths,omitempty"`
	Components Components            `json:"components,omitempty"`
}

Document is a small OpenAPI 3.1 document model used by generated contracts. It intentionally covers the subset Nucleus scaffolds need today.

func NewDocument 

func NewDocument(title, version string) *Document

func (*Document) AddSchema 

func (d *Document) AddSchema(name string, schema Schema)

func (*Document) AddSecurityScheme 

func (d *Document) AddSecurityScheme(name string, scheme SecurityScheme)

AddSecurityScheme registers a named scheme under components.securitySchemes (lazily creating the map). Reference it by the same name from a SecurityRequirement.

func (*Document) EnsureComponents 

func (d *Document) EnsureComponents()

func (*Document) EnsurePaths 

func (d *Document) EnsurePaths()

type DocumentProvider 

type DocumentProvider func() *Document

DocumentProvider returns the current OpenAPI document to serve.

type Info 

type Info struct {
	Title       string `json:"title"`
	Version     string `json:"version"`
	Description string `json:"description,omitempty"`
}

type MediaType 

type MediaType struct {
	Schema Schema `json:"schema"`
}

type Operation 

type Operation struct {
	OperationID string   `json:"operationId,omitempty"`
	Summary     string   `json:"summary,omitempty"`
	Description string   `json:"description,omitempty"`
	Tags        []string `json:"tags,omitempty"`
	// Security overrides the document's global security for this operation. A
	// nil value inherits the global default; a non-nil value (including an empty
	// slice — see PublicSecurity) replaces it. Pointer so an explicit empty
	// override survives JSON marshalling (a plain slice would be omitted).
	Security    *[]SecurityRequirement `json:"security,omitempty"`
	Parameters  []Parameter            `json:"parameters,omitempty"`
	RequestBody *RequestBody           `json:"requestBody,omitempty"`
	Responses   map[string]Response    `json:"responses"`
}

type Parameter 

type Parameter struct {
	Name        string `json:"name"`
	In          string `json:"in"`
	Description string `json:"description,omitempty"`
	Required    bool   `json:"required,omitempty"`
	Schema      Schema `json:"schema"`
}

func PathParameter 

func PathParameter(name string, schema Schema, description string) Parameter

func QueryParameter 

func QueryParameter(name string, schema Schema, description string, required bool) Parameter

func SearchQueryParameter 

func SearchQueryParameter(description string) Parameter

type PathItem 

type PathItem struct {
	Get    *Operation `json:"get,omitempty"`
	Post   *Operation `json:"post,omitempty"`
	Put    *Operation `json:"put,omitempty"`
	Delete *Operation `json:"delete,omitempty"`
}

type RequestBody 

type RequestBody struct {
	Required bool                 `json:"required,omitempty"`
	Content  map[string]MediaType `json:"content"`
}

func JSONRequestBody 

func JSONRequestBody(schema Schema, required bool) *RequestBody

type Response 

type Response struct {
	Description string               `json:"description"`
	Content     map[string]MediaType `json:"content,omitempty"`
}

func EmptyResponse 

func EmptyResponse(description string) Response

func ErrorResponse 

func ErrorResponse(description string) Response

func JSONResponse 

func JSONResponse(description string, schema Schema) Response

type Schema 

type Schema struct {
	Ref                  string            `json:"$ref,omitempty"`
	Type                 string            `json:"type,omitempty"`
	Format               string            `json:"format,omitempty"`
	Description          string            `json:"description,omitempty"`
	Properties           map[string]Schema `json:"properties,omitempty"`
	Items                *Schema           `json:"items,omitempty"`
	Required             []string          `json:"required,omitempty"`
	AdditionalProperties *Schema           `json:"additionalProperties,omitempty"`
}

func ArraySchema 

func ArraySchema(items Schema) Schema

func CollectionEnvelopeSchema 

func CollectionEnvelopeSchema(item Schema) Schema

func DataEnvelopeSchema 

func DataEnvelopeSchema(data Schema) Schema

func ErrorSchema 

func ErrorSchema() Schema

func IDSchema 

func IDSchema() Schema

func ObjectSchema 

func ObjectSchema(properties map[string]Schema, required ...string) Schema

func RefSchema 

func RefSchema(name string) Schema

type SecurityRequirement 

type SecurityRequirement map[string][]string

SecurityRequirement is an OpenAPI Security Requirement Object (§4.8.30): a map of security-scheme name to the scope names it requires. HTTP and apiKey schemes take no scopes, so their requirement value is an empty slice.

func Require 

func Require(scheme string, scopes ...string) SecurityRequirement

Require builds a Security Requirement naming one registered scheme, with optional OAuth-style scopes (empty for http/apiKey schemes). A nil scope slice — including a spread nil — is normalised to an empty list, the correct serialisation for a scheme that takes no scopes.

type SecurityScheme 

type SecurityScheme struct {
	Type         string `json:"type"` // "http" | "apiKey"
	Description  string `json:"description,omitempty"`
	Scheme       string `json:"scheme,omitempty"`       // type=http: "bearer" | "basic"
	BearerFormat string `json:"bearerFormat,omitempty"` // scheme=bearer: token-shape hint, e.g. "JWT"
	Name         string `json:"name,omitempty"`         // type=apiKey: request element name
	In           string `json:"in,omitempty"`           // type=apiKey: "header" | "query" | "cookie"
}

SecurityScheme is an OpenAPI 3.1 Security Scheme Object (§4.8.27). Nucleus models the two schemes a generated contract realistically needs — HTTP authentication (`type: http`, e.g. `bearer` or `basic`) and API keys (`type: apiKey`). oauth2 / openIdConnect flows are out of scope for the scaffold subset.

func APIKeyScheme 

func APIKeyScheme(name, in string) SecurityScheme

APIKeyScheme returns an apiKey Security Scheme carried in the named request element. in is one of "header", "query" or "cookie".

func BearerAuthScheme 

func BearerAuthScheme(bearerFormat string) SecurityScheme

BearerAuthScheme returns an HTTP bearer Security Scheme. bearerFormat is an optional hint for the token shape (e.g. "JWT") and may be empty.

type Server 

type Server struct {
	URL         string `json:"url"`
	Description string `json:"description,omitempty"`
}

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.