README.md

openapi

Tier: Platform · Status: Full · Java original: springdoc-openapi · .NET project: Swashbuckle.AspNetCore

Overview

openapi generates an OpenAPI 3.1 document from registered RouteDef descriptors plus the Go types they consume / return. The generator walks struct types via reflection (json tags, with time.Time mapping to string format=date-time), registers schemas under #/components/schemas/{TypeName}, and serves the result at /openapi.json with a Swagger-UI shim at /openapi/ui.

The generator is deliberately small — it has no annotation framework, no DI, no codegen step. You hand-register routes and the Go types do the rest through reflection.

Public surface

type Info struct { Title, Version, Description string }
type Server struct { URL, Description string }

type RouteDef struct {
    Method, Path        string
    Summary, Description string
    Tags                []string
    Request             any   // sample value of the body type, or nil
    Response            any   // sample value of the success response, or nil
    Status              int   // success status code; defaults to 200/201
}

type Builder struct{ Info Info; Servers []Server }
func New(info Info) *Builder
func (*Builder) AddServer(Server) *Builder
func (*Builder) Add(RouteDef) *Builder
func (*Builder) Build() Document
func (*Builder) Handler() http.Handler

type Document struct { ... }     // serialisable OAS 3.1 root
type Operation struct { ... }

Quick start

import (
    "net/http"
    "github.com/fireflyframework/fireflyframework-go/openapi"
)

type PlaceOrderRequest struct {
    Customer string `json:"customer"`
    Quantity int    `json:"quantity"`
}
type Order struct {
    ID       string `json:"id"`
    Customer string `json:"customer"`
    Quantity int    `json:"quantity"`
}

doc := openapi.New(openapi.Info{Title: "Orders API", Version: "1.0.0"}).
    AddServer(openapi.Server{URL: "https://api.example.com"}).
    Add(openapi.RouteDef{
        Method: http.MethodPost, Path: "/api/v1/orders",
        Summary: "Place an order",
        Tags:    []string{"orders"},
        Request: PlaceOrderRequest{},
        Response: Order{},
    })

mux := http.NewServeMux()
mux.Handle("/", doc.Handler())  // serves /openapi.json + /openapi/ui

Schema mapping

Go kind	OpenAPI shape
string	{"type":"string"}
bool	{"type":"boolean"}
int* / uint*	{"type":"integer","format":"int64"}
float32 / float64	{"type":"number"}
[]T	{"type":"array","items":...}
map[K]V	{"type":"object","additionalProperties":true}
struct	$ref: #/components/schemas/{TypeName} (or inline if anonymous)
time.Time	{"type":"string","format":"date-time"}
pointer	unwrap → underlying kind

The default error response (default) uses #/components/schemas/ProblemDetail so every operation surfaces RFC 7807 errors uniformly.

Testing

cd openapi
go test ./...

Covers Operation registration, schema generation for primitives / slices / structs / time.Time, the /openapi.json and /openapi/ui handlers, and the canonical ProblemDetail error response.