-
Notifications
You must be signed in to change notification settings - Fork 0
Configuration
app := rex.New(openapi.WithOpenAPI(openapi.NewConfig( openapi.WithTitle("Orders API"), openapi.WithVersion("2.1.0"), openapi.WithDescription("Order placement, fulfilment and returns."), openapi.WithTags( openapi.Tag{Name: "orders", Description: "Order lifecycle"}, ), )))
openapi.WithOpenAPI(nil) takes the defaults: title "API", version "1.0.0",
served at /openapi.json, default router only.
There is no field-by-field merge. A partial struct literal leaves everything else at its zero value:
// Wrong: Title "", Version "", ServePath "" — no path to serve at. openapi.WithOpenAPI(&openapi.Config{Description: "..."}) // Right. openapi.WithOpenAPI(openapi.NewConfig(openapi.WithDescription("...")))
The merge used to exist and behaved as a trap: fields it forgot were silently ignored, fields it copied unconditionally were zeroed by a partial literal, and a deliberate zero could not be expressed at all.
type Config struct { Title string // "API" Version string // "1.0.0" Description string ServePath string // "/openapi.json" Tags []Tag IncludeRouters []string // empty → the default router only ExcludeRouters []string // applied after IncludeRouters ServeOnRouter string // empty → the default router }
WithTitle(s) / WithVersion(s) / WithDescription(s)
|
the info section |
WithTags(tags...) |
top-level tag descriptions; merged, last wins on a duplicate name |
WithServePath(p) |
where the document is served |
WithServeOnRouter(name) |
which router serves it |
WithIncludeRouters(names...) |
whose routes appear; "*" for all |
WithExcludeRouters(names...) |
omit these, after include |
Version is the API version, not the build. Bump it when the contract
changes, not on every deploy — a client generator keys off it, and a version
that changes hourly is noise.
openapi.WithVersion("2.1.0")
openapi.NewConfig( openapi.WithTitle("Orders API"), openapi.WithVersion(apiVersion), // a constant, bumped deliberately openapi.WithDescription(strings.TrimSpace(` Order placement, fulfilment and returns. Errors are RFC 9457 problem documents. `)), openapi.WithTags( openapi.Tag{Name: "orders", Description: "Order lifecycle"}, openapi.Tag{Name: "returns", Description: "Return authorisations"}, ), // Explicit rather than implicit, so the intent survives a new router. openapi.WithIncludeRouters("default"), openapi.WithServeOnRouter("default"), )
g := openapi.NewGenerator(cfg, schemes) doc, err := g.Generate(routes)
Useful for writing the document to a file in CI so a contract change shows up in a diff:
func TestOpenAPISnapshot(t *testing.T) { doc, err := openapi.NewGenerator(cfg, nil).Generate(routes()) if err != nil { t.Fatal(err) } got, _ := json.MarshalIndent(doc, "", " ") // compare with testdata/openapi.json }
That is worth having: it turns "we accidentally changed the API" into a failing test rather than a support ticket.
Ecosystem