emitter

Documentation

Overview

Package emitter builds the final OpenAPI 3.1 document from merged operations and serializes it to YAML or JSON.

Index

• func Build(info model.Info, routeOps []RouteOperation) (*model.Document, error)
• func Marshal(doc *model.Document, format Format) ([]byte, error)
• func Validate(doc *model.Document) error
• type Format
• type RouteOperation

Functions

func Build

func Build(info model.Info, routeOps []RouteOperation) (*model.Document, error)

Build assembles a Document from routeOps. info.Title/Version populate the required Info object.

func Marshal

func Marshal(doc *model.Document, format Format) ([]byte, error)

Marshal serializes doc in the requested format. Both formats produce deterministic output — map-backed fields (Paths, Schemas, Responses...) come out with keys sorted alphabetically rather than in Go's randomized map iteration order.

func Validate

func Validate(doc *model.Document) error

Validate checks that doc is structurally valid OpenAPI, using kin-openapi as an independent authority rather than trusting our own struct definitions. It marshals doc to JSON internally — a format kin-openapi's loader handles unambiguously — so the check doesn't depend on which format the CLI eventually writes to disk.

Known limitation: kin-openapi v0.135.0 models the Schema Object per OpenAPI 3.0 (e.g. "nullable" and "exclusiveMinimum"/"exclusiveMaximum" as booleans, no "webhooks"/"jsonSchemaDialect" support). It still catches real structural mistakes — missing required fields, malformed $ref, wrong parameter/response shapes — but it is not a strict OpenAPI 3.1 conformance check. A newer kin-openapi (>= v0.140.0) fixes this properly but requires Go >= 1.25; revisit this once that's no longer a cost.

Types

type Format

type Format string

Format selects the output serialization.

const (
	YAML Format = "yaml"
	JSON Format = "json"
)

type RouteOperation

type RouteOperation struct {
	Method    string
	Path      string
	Operation *model.Operation
}

RouteOperation binds one merged Operation to the method + path it serves.