openapi

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Feb 7, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package openapi provides OpenAPI 3.1 specification generation.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ToJSON 

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

ToJSON converts the spec to JSON bytes.

func ToString 

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

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

func ToYAML 

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

ToYAML converts the spec to YAML bytes.

func WriteFile 

func WriteFile(path string, spec *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 *Spec) error

WriteJSON writes the spec as JSON.

func WriteYAML 

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

WriteYAML writes the spec as YAML.

Types

type Components 

type Components struct {
	Schemas         map[string]*Schema         `json:"schemas,omitempty" yaml:"schemas,omitempty"`
	Responses       map[string]*Response       `json:"responses,omitempty" yaml:"responses,omitempty"`
	Parameters      map[string]*Parameter      `json:"parameters,omitempty" yaml:"parameters,omitempty"`
	Examples        map[string]*Example        `json:"examples,omitempty" yaml:"examples,omitempty"`
	RequestBodies   map[string]*RequestBody    `json:"requestBodies,omitempty" yaml:"requestBodies,omitempty"`
	Headers         map[string]*Header         `json:"headers,omitempty" yaml:"headers,omitempty"`
	SecuritySchemes map[string]*SecurityScheme `json:"securitySchemes,omitempty" yaml:"securitySchemes,omitempty"`
}

Components holds reusable objects.

type Contact 

type Contact struct {
	Name  string `json:"name,omitempty" yaml:"name,omitempty"`
	URL   string `json:"url,omitempty" yaml:"url,omitempty"`
	Email string `json:"email,omitempty" yaml:"email,omitempty"`
}

Contact information for the API.

type Example 

type Example struct {
	Summary       string `json:"summary,omitempty" yaml:"summary,omitempty"`
	Description   string `json:"description,omitempty" yaml:"description,omitempty"`
	Value         any    `json:"value,omitempty" yaml:"value,omitempty"`
	ExternalValue string `json:"externalValue,omitempty" yaml:"externalValue,omitempty"`
}

Example describes an example value.

type Format 

type Format string

Format represents the output format. 

const (
	FormatJSON Format = "json"
	FormatYAML Format = "yaml"
)

type Generator 

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

Generator converts inference results to OpenAPI specs.

func NewGenerator 

func NewGenerator(options GeneratorOptions) *Generator

NewGenerator creates a new OpenAPI generator.

func (*Generator) Generate 

func (g *Generator) Generate(result *inference.InferenceResult) *Spec

Generate creates an OpenAPI spec from inference results.

type GeneratorOptions 

type GeneratorOptions struct {
	Version     Version
	Title       string
	Description string
	APIVersion  string
	Servers     []string
}

GeneratorOptions configures the OpenAPI generator.

func DefaultGeneratorOptions 

func DefaultGeneratorOptions() GeneratorOptions

DefaultGeneratorOptions returns default options. 

type Header struct {
	Description string  `json:"description,omitempty" yaml:"description,omitempty"`
	Required    bool    `json:"required,omitempty" yaml:"required,omitempty"`
	Schema      *Schema `json:"schema,omitempty" yaml:"schema,omitempty"`
}

Header describes a single header.

type Info 

type Info struct {
	Title       string   `json:"title" yaml:"title"`
	Description string   `json:"description,omitempty" yaml:"description,omitempty"`
	Version     string   `json:"version" yaml:"version"`
	Contact     *Contact `json:"contact,omitempty" yaml:"contact,omitempty"`
	License     *License `json:"license,omitempty" yaml:"license,omitempty"`
}

Info provides metadata about the API.

type License 

type License struct {
	Name string `json:"name" yaml:"name"`
	URL  string `json:"url,omitempty" yaml:"url,omitempty"`
}

License information for the API.

type MediaType 

type MediaType struct {
	Schema   *Schema            `json:"schema,omitempty" yaml:"schema,omitempty"`
	Example  any                `json:"example,omitempty" yaml:"example,omitempty"`
	Examples map[string]Example `json:"examples,omitempty" yaml:"examples,omitempty"`
}

MediaType provides schema and examples for the media type.

type OAuthFlow 

type OAuthFlow struct {
	AuthorizationUrl string            `json:"authorizationUrl,omitempty" yaml:"authorizationUrl,omitempty"`
	TokenUrl         string            `json:"tokenUrl,omitempty" yaml:"tokenUrl,omitempty"`
	RefreshUrl       string            `json:"refreshUrl,omitempty" yaml:"refreshUrl,omitempty"`
	Scopes           map[string]string `json:"scopes" yaml:"scopes"`
}

OAuthFlow defines a single OAuth 2.0 flow.

type OAuthFlows 

type OAuthFlows struct {
	Implicit          *OAuthFlow `json:"implicit,omitempty" yaml:"implicit,omitempty"`
	Password          *OAuthFlow `json:"password,omitempty" yaml:"password,omitempty"`
	ClientCredentials *OAuthFlow `json:"clientCredentials,omitempty" yaml:"clientCredentials,omitempty"`
	AuthorizationCode *OAuthFlow `json:"authorizationCode,omitempty" yaml:"authorizationCode,omitempty"`
}

OAuthFlows defines OAuth 2.0 flows.

type Operation 

type Operation struct {
	Tags        []string              `json:"tags,omitempty" yaml:"tags,omitempty"`
	Summary     string                `json:"summary,omitempty" yaml:"summary,omitempty"`
	Description string                `json:"description,omitempty" yaml:"description,omitempty"`
	OperationID string                `json:"operationId,omitempty" yaml:"operationId,omitempty"`
	Parameters  []Parameter           `json:"parameters,omitempty" yaml:"parameters,omitempty"`
	RequestBody *RequestBody          `json:"requestBody,omitempty" yaml:"requestBody,omitempty"`
	Responses   map[string]Response   `json:"responses" yaml:"responses"`
	Deprecated  bool                  `json:"deprecated,omitempty" yaml:"deprecated,omitempty"`
	Security    []SecurityRequirement `json:"security,omitempty" yaml:"security,omitempty"`
}

Operation describes a single API operation on a path.

type Parameter 

type Parameter struct {
	Name            string  `json:"name" yaml:"name"`
	In              string  `json:"in" yaml:"in"` // query, header, path, cookie
	Description     string  `json:"description,omitempty" yaml:"description,omitempty"`
	Required        bool    `json:"required,omitempty" yaml:"required,omitempty"`
	Deprecated      bool    `json:"deprecated,omitempty" yaml:"deprecated,omitempty"`
	AllowEmptyValue bool    `json:"allowEmptyValue,omitempty" yaml:"allowEmptyValue,omitempty"`
	Schema          *Schema `json:"schema,omitempty" yaml:"schema,omitempty"`
	Example         any     `json:"example,omitempty" yaml:"example,omitempty"`
}

Parameter describes a single operation parameter.

type PathItem 

type PathItem struct {
	Summary     string      `json:"summary,omitempty" yaml:"summary,omitempty"`
	Description string      `json:"description,omitempty" yaml:"description,omitempty"`
	Get         *Operation  `json:"get,omitempty" yaml:"get,omitempty"`
	Put         *Operation  `json:"put,omitempty" yaml:"put,omitempty"`
	Post        *Operation  `json:"post,omitempty" yaml:"post,omitempty"`
	Delete      *Operation  `json:"delete,omitempty" yaml:"delete,omitempty"`
	Options     *Operation  `json:"options,omitempty" yaml:"options,omitempty"`
	Head        *Operation  `json:"head,omitempty" yaml:"head,omitempty"`
	Patch       *Operation  `json:"patch,omitempty" yaml:"patch,omitempty"`
	Trace       *Operation  `json:"trace,omitempty" yaml:"trace,omitempty"`
	Parameters  []Parameter `json:"parameters,omitempty" yaml:"parameters,omitempty"`
}

PathItem describes operations available on a single path.

type RequestBody 

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

RequestBody describes a single request body.

type Response 

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

Response describes a single response from an API operation.

type Schema 

type Schema struct {
	// Core
	Type   any    `json:"type,omitempty" yaml:"type,omitempty"` // string or []string for nullable
	Format string `json:"format,omitempty" yaml:"format,omitempty"`

	// Metadata
	Title       string `json:"title,omitempty" yaml:"title,omitempty"`
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	Default     any    `json:"default,omitempty" yaml:"default,omitempty"`

	// Validation
	Enum  []any `json:"enum,omitempty" yaml:"enum,omitempty"`
	Const any   `json:"const,omitempty" yaml:"const,omitempty"`

	// Numeric
	MultipleOf       *float64 `json:"multipleOf,omitempty" yaml:"multipleOf,omitempty"`
	Maximum          *float64 `json:"maximum,omitempty" yaml:"maximum,omitempty"`
	ExclusiveMaximum *float64 `json:"exclusiveMaximum,omitempty" yaml:"exclusiveMaximum,omitempty"`
	Minimum          *float64 `json:"minimum,omitempty" yaml:"minimum,omitempty"`
	ExclusiveMinimum *float64 `json:"exclusiveMinimum,omitempty" yaml:"exclusiveMinimum,omitempty"`

	// String
	MaxLength *int   `json:"maxLength,omitempty" yaml:"maxLength,omitempty"`
	MinLength *int   `json:"minLength,omitempty" yaml:"minLength,omitempty"`
	Pattern   string `json:"pattern,omitempty" yaml:"pattern,omitempty"`

	// Array
	Items       *Schema `json:"items,omitempty" yaml:"items,omitempty"`
	MaxItems    *int    `json:"maxItems,omitempty" yaml:"maxItems,omitempty"`
	MinItems    *int    `json:"minItems,omitempty" yaml:"minItems,omitempty"`
	UniqueItems bool    `json:"uniqueItems,omitempty" yaml:"uniqueItems,omitempty"`

	// Object
	Properties           map[string]*Schema `json:"properties,omitempty" yaml:"properties,omitempty"`
	Required             []string           `json:"required,omitempty" yaml:"required,omitempty"`
	AdditionalProperties any                `json:"additionalProperties,omitempty" yaml:"additionalProperties,omitempty"`
	MaxProperties        *int               `json:"maxProperties,omitempty" yaml:"maxProperties,omitempty"`
	MinProperties        *int               `json:"minProperties,omitempty" yaml:"minProperties,omitempty"`

	// Composition
	AllOf []*Schema `json:"allOf,omitempty" yaml:"allOf,omitempty"`
	OneOf []*Schema `json:"oneOf,omitempty" yaml:"oneOf,omitempty"`
	AnyOf []*Schema `json:"anyOf,omitempty" yaml:"anyOf,omitempty"`
	Not   *Schema   `json:"not,omitempty" yaml:"not,omitempty"`

	// Reference
	Ref string `json:"$ref,omitempty" yaml:"$ref,omitempty"`

	// Examples (OpenAPI 3.1)
	Examples []any `json:"examples,omitempty" yaml:"examples,omitempty"`

	// Deprecated
	Deprecated bool `json:"deprecated,omitempty" yaml:"deprecated,omitempty"`

	// Read/Write only
	ReadOnly  bool `json:"readOnly,omitempty" yaml:"readOnly,omitempty"`
	WriteOnly bool `json:"writeOnly,omitempty" yaml:"writeOnly,omitempty"`
}

Schema represents a JSON Schema (OpenAPI 3.1 uses JSON Schema 2020-12).

type SecurityRequirement 

type SecurityRequirement map[string][]string

SecurityRequirement defines security requirements for an operation.

type SecurityScheme 

type SecurityScheme struct {
	Type             string      `json:"type" yaml:"type"` // apiKey, http, oauth2, openIdConnect
	Description      string      `json:"description,omitempty" yaml:"description,omitempty"`
	Name             string      `json:"name,omitempty" yaml:"name,omitempty"`                         // for apiKey
	In               string      `json:"in,omitempty" yaml:"in,omitempty"`                             // for apiKey: query, header, cookie
	Scheme           string      `json:"scheme,omitempty" yaml:"scheme,omitempty"`                     // for http
	BearerFormat     string      `json:"bearerFormat,omitempty" yaml:"bearerFormat,omitempty"`         // for http bearer
	Flows            *OAuthFlows `json:"flows,omitempty" yaml:"flows,omitempty"`                       // for oauth2
	OpenIdConnectUrl string      `json:"openIdConnectUrl,omitempty" yaml:"openIdConnectUrl,omitempty"` // for openIdConnect
}

SecurityScheme defines a security scheme.

type Server 

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

Server represents an API server.

type Spec 

type Spec struct {
	OpenAPI    string               `json:"openapi" yaml:"openapi"`
	Info       Info                 `json:"info" yaml:"info"`
	Servers    []Server             `json:"servers,omitempty" yaml:"servers,omitempty"`
	Paths      map[string]*PathItem `json:"paths" yaml:"paths"`
	Components *Components          `json:"components,omitempty" yaml:"components,omitempty"`
}

Spec represents an OpenAPI 3.x specification.

func FromJSON 

func FromJSON(data []byte) (*Spec, error)

FromJSON parses a spec from JSON bytes.

func FromYAML 

func FromYAML(data []byte) (*Spec, error)

FromYAML parses a spec from YAML bytes.

func GenerateFromInference 

func GenerateFromInference(result *inference.InferenceResult, options GeneratorOptions) *Spec

GenerateFromInference is a convenience function.

func ReadFile 

func ReadFile(path string) (*Spec, error)

ReadFile reads an OpenAPI spec from a file. Format is determined by file extension (.json or .yaml/.yml).

type Version 

type Version string

Version represents the OpenAPI version to generate. 

const (
	Version30 Version = "3.0.3"
	Version31 Version = "3.1.0"
)

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.