openapi

Documentation

Index

• func Generate(opts *GenerateOptions, specs ...AbstractServiceSpec) error
• func OnRequest[T goat.AbstractStateMachine, I AbstractSchema, O AbstractSchema](spec *ServiceSpec[T], state goat.AbstractState, method HTTPMethod, path string, ...)
• type AbstractSchema
• type AbstractServiceSpec
• type GenerateOptions
• type HTTPMethod
• type RequestOption
  • func WithOperationID(id string) RequestOption
  • func WithRequestBodyOptional() RequestOption
  • func WithStatusCode(code StatusCode) RequestOption
• type Response
  • func SendTo[O AbstractSchema](ctx context.Context, target goat.AbstractStateMachine, event O) Response[O]
• type Schema
• type ServiceSpec
  • func NewServiceSpec[T goat.AbstractStateMachine](prototype T) *ServiceSpec[T]
• type StatusCode

Functions

func Generate

func Generate(opts *GenerateOptions, specs ...AbstractServiceSpec) error

Generate generates an OpenAPI 3.0 specification file from one or more service specifications. It analyzes the registered endpoints and schemas, and writes a YAML file to the specified output directory.

Parameters:

• opts: Configuration options for the generation (Title is required)
• specs: One or more OpenAPI service specifications to include in the generated spec

Returns:

• error: An error if Title is empty, or if file creation/writing fails

func OnRequest

func OnRequest[T goat.AbstractStateMachine, I AbstractSchema, O AbstractSchema](
	spec *ServiceSpec[T],
	state goat.AbstractState,
	method HTTPMethod,
	path string,
	handler func(context.Context, I, T) Response[O],
	opts ...RequestOption,
)

OnRequest registers an OpenAPI endpoint handler with the given specification.

Type parameters:

• T: The state machine type
• I: The request schema type (must implement AbstractSchema)
• O: The response schema type (must implement AbstractSchema)

Parameters:

• spec: The OpenAPI service specification to register the endpoint with
• state: The state in which this endpoint is active
• method: The HTTP method (e.g., HTTPMethodGet, HTTPMethodPost)
• path: The URL path for the endpoint (e.g., "/users/{id}")
• handler: The function that handles requests for this endpoint
• opts: Optional configuration options (WithOperationID, WithStatusCode)

Types

type AbstractSchema

type AbstractSchema interface {
	goat.AbstractEvent
	// contains filtered or unexported methods
}

type AbstractServiceSpec

type AbstractServiceSpec interface {
	// contains filtered or unexported methods
}

type GenerateOptions

type GenerateOptions struct {
	// OutputDir is the directory where the OpenAPI spec file will be written.
	// Defaults to "./openapi" if not specified.
	OutputDir string

	// Title is the title of the API (required).
	// This appears in the "info.title" field of the OpenAPI spec.
	Title string

	// Version is the version of the API.
	// Defaults to "1.0.0" if not specified.
	Version string

	// Filename is the name of the generated OpenAPI spec file.
	// Defaults to "openapi.yaml" if not specified.
	Filename string
}

GenerateOptions contains configuration options for OpenAPI spec generation.

type HTTPMethod

type HTTPMethod interface {
	String() string
	// contains filtered or unexported methods
}

var (
	HTTPMethodGet    HTTPMethod = httpMethodValue("GET")
	HTTPMethodPost   HTTPMethod = httpMethodValue("POST")
	HTTPMethodPut    HTTPMethod = httpMethodValue("PUT")
	HTTPMethodDelete HTTPMethod = httpMethodValue("DELETE")
)

type RequestOption

type RequestOption func(*requestConfig)

RequestOption is a functional option for configuring an OpenAPI request handler.

func WithOperationID

func WithOperationID(id string) RequestOption

WithOperationID sets a custom operation ID for the endpoint. If the operationID is empty, the operationId field will be omitted from the generated OpenAPI spec.

func WithRequestBodyOptional

func WithRequestBodyOptional() RequestOption

WithRequestBodyOptional marks the request body as optional in the generated OpenAPI spec.

func WithStatusCode

func WithStatusCode(code StatusCode) RequestOption

WithStatusCode sets a custom HTTP status code for the endpoint response. The default status code is 200 (StatusOK) if not specified.

type Response

type Response[O AbstractSchema] interface {
	// contains filtered or unexported methods
}

Response represents a response that will be sent back in an OpenAPI RPC handler. You must create this by calling SendTo with your response message.

func SendTo

func SendTo[O AbstractSchema](ctx context.Context, target goat.AbstractStateMachine, event O) Response[O]

SendTo sends an OpenAPI response event to the target state machine and returns a Response. This is the only way to create a Response, enforcing that all responses go through the proper event system.

Type parameters:

• O: The response schema type (must implement AbstractSchema)

Parameters:

• ctx: The context for the event
• target: The target state machine to send the event to
• event: The response event to send

Returns:

• Response[O]: A sealed response type that can only be created through this function

type Schema

type Schema[Sender goat.AbstractStateMachine, Recipient goat.AbstractStateMachine] struct {
	goat.Event[Sender, Recipient]
	// contains filtered or unexported fields
}

type ServiceSpec

type ServiceSpec[T goat.AbstractStateMachine] struct {
	*goat.StateMachineSpec[T]
	// contains filtered or unexported fields
}

func NewServiceSpec

func NewServiceSpec[T goat.AbstractStateMachine](prototype T) *ServiceSpec[T]

NewServiceSpec creates a new OpenAPI service specification for the given state machine prototype. The prototype defines which state machine implementation will receive requests and how its states will be exposed via OpenAPI.

Parameters:

• prototype: The state machine instance used as the template for the service

Returns a specification that can be configured with states and handlers.

Example:

spec := openapi.NewServiceSpec(&UserStateMachine{})
openapi.OnRequest(spec, UserState{}, HTTPMethodPost, "/users", handleCreateUser)

type StatusCode

type StatusCode int

const (
	StatusOK                  StatusCode = 200
	StatusCreated             StatusCode = 201
	StatusAccepted            StatusCode = 202
	StatusNoContent           StatusCode = 204
	StatusBadRequest          StatusCode = 400
	StatusUnauthorized        StatusCode = 401
	StatusForbidden           StatusCode = 403
	StatusNotFound            StatusCode = 404
	StatusConflict            StatusCode = 409
	StatusInternalServerError StatusCode = 500
	StatusServiceUnavailable  StatusCode = 503
)