openapi

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: 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 (3.1+)
	Format string `json:"format,omitempty" yaml:"format,omitempty"`

	// Nullable (OpenAPI 3.0 only - use type array with "null" for 3.1+)
	Nullable bool `json:"nullable,omitempty" yaml:"nullable,omitempty"`

	// Example (OpenAPI 3.0 - use Examples array for 3.1+)
	Example any `json:"example,omitempty" yaml:"example,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"
	Version32 Version = "3.2.0"
)

Source Files

View all Source files

Directories

Path Synopsis
Package convert provides OpenAPI specification version conversion.
 Package convert provides OpenAPI specification version conversion.
Package validate provides OpenAPI specification validation using libopenapi.
 Package validate provides OpenAPI specification validation using libopenapi.

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.