Changelog

v1.2.0

A bug-fix + DX release. Closes the four bugs that produced wrong specs at runtime (self-referential structs, ignored ContentType, silent bearer fallback, dormant type-change detector) and finally ships the public API the README has been documenting all along.

go get github.com/gopackx/open-swag-go@v1.2.0

Breaking change

The Response struct is renamed to ResponseSpec so openswag.Response(desc, schema) can be the constructor the README documents. Field-keyed literals inside openswag.Responses{ ... } keep compiling unchanged — only bare openswag.Response{...} literals need to migrate (use openswag.Response("desc", T{}) or openswag.ResponseSpec{...}).

Fixed

fix(schema): Self-referential structs (e.g. type Category struct { Children []Category }) no longer cause a stack overflow during spec generation. fromReflectType now threads a visiting-type set; back-edges return a bounded object schema with a description note.
fix(openapi): RequestBody.ContentType is now honored end-to-end. multipart/form-data and application/x-www-form-urlencoded bodies appear in the spec under the correct media type instead of being silently rewritten to application/json. Added pkg/spec.RequestBody.WithContent(mediaType, schema) to back the new behavior.
fix(openapi): Custom security scheme names referenced from Endpoint.Security are no longer silently coerced into http-bearer. Unknown names are now omitted from components.securitySchemes so typos surface immediately. Register custom schemes explicitly via the new Config.Auth.Schemes field.
fix(versioning): compareOperations now produces entries for BreakingTypeChanged. Changes to a request-body field's JSON type/format and changes to a parameter's schema type are flagged as breaking, with migration hints. Also fixed a latent index-out-of-range bug in getMigrationGuide (short descriptions could panic the migration formatter).

New public API

The README has documented these helpers for several versions, but the package never exposed them — Quick Start examples could not compile. They exist now:

Request body builders: Body(schema), BodyWithDesc(desc, schema), FormBody(schema), FormURLEncodedBody(schema) — all return *RequestBody ready to drop into Endpoint.RequestBody.
Response constructor: Response(desc, schema...) returns a ResponseSpec. Pass the schema as the second argument or omit it for empty responses (e.g. 204 No Content). The type alias Responses = map[int]ResponseSpec exists for the decorator-style map literal.
Parameter helpers: PathParam, QueryParam, RequiredQueryParam, HeaderParam, CookieParam — all return a Parameter ready for Endpoint.Parameters.
Auth scheme helpers: BearerAuth(name), APIKeyAuth(name, header), APIKeyQueryAuth(name, param), BasicAuth(name), CookieAuth(name, cookieName) — all return an AuthScheme for registration via Config.Auth.Schemes.
Config surface: Config.Auth AuthConfig (with PersistCredentials and Schemes fields) plus the AuthScheme struct. The new SecurityCookieAuth constant joins the existing Security* family for the predefined-name shortcut.

Migrating from v1.1.1

Replace bare openswag.Response{...} literals with openswag.Response("desc", Schema{}) or openswag.ResponseSpec{...}. Literals inside openswag.Responses{ ... } (or the equivalent typed map) continue to compile via Go's composite-literal type inference.

If you were referencing custom security scheme names from Endpoint.Security and relying on them magically becoming http-bearer, register them explicitly:

Auth: openswag.AuthConfig{
    Schemes: []openswag.AuthScheme{
        openswag.BearerAuth(openswag.SecurityBearerAuth),
        openswag.APIKeyAuth("apiKey", "X-API-Key"),
    },
},

File-upload endpoints that previously had a ContentType: "multipart/form-data" set on RequestBody will now produce a different spec than before — review your generated openapi.json and update downstream clients/code generators accordingly.

v1.1.1

Cleaner specs out of the box. Examples are now opt-in: you only see them where you ask for them, and null is supported as a first-class example value. Fully backwards-compatible — no API signatures changed.

go get github.com/gopackx/open-swag-go@v1.1.1

Behavior change worth flagging

Examples are now opt-in. Auto-generated example values for primitive fields have been removed. Previously every primitive field got a placeholder ("string", 0, false, …) in the spec even without an example tag, which produced noisy Scalar UI. Now examples appear only where you set example:"..." on the field.

What's new

example:"null" literal — Setting example:"null" on any field type now produces actual JSON null in the spec (previously only worked for slices/maps). Useful for documenting nullable fields.

Fixed

Stray "example": null entries no longer leak into request body schemas when no example is provided (typed-nil interface bug).

Migrating from v1.1.0

If you relied on the old auto-generated placeholders to populate the Scalar UI, add explicit example:"..." tags to the fields you want shown — see the Migration Guide for details.

v1.1.0

All 12 fixes are backwards-compatible — no public API signatures changed, only additive struct fields and behavior corrections.

go get github.com/gopackx/open-swag-go@v1.1.0

Critical Fixes

fix(spec): Fixed port-to-string conversion in CommonServers.Localhost() and LocalhostServer() — replaced broken string(rune(port)) with strconv.Itoa(port). Also fixed the same pattern in intToString() in openapi.go.
fix(schema): Example tag values are now coerced to the correct type via ConvertExampleToType(). example:"42" on an int64 field now produces the integer 42, not the string "42". Applied in pkg/schema/tags.go, openapi.go, and pkg/examples/generator.go.
fix(schema): $ref pointers are no longer silently dropped during schema conversion — added Ref: s.Ref mapping in convertSchema().

High Severity Fixes

fix(schema): Embedded (anonymous) struct fields are now detected via field.Anonymous and their properties are promoted into the parent schema.
fix(schema): map[K]V types now correctly generate {"type":"object","additionalProperties":{...}}. Added AdditionalProperties field to schema.Schema and conversion in convertSchema().
fix(schema): interface{}/any fields now produce an empty schema {} (accepts any type) instead of {"type":"object"}. Validator updated to accept empty schemas.

Medium Severity Fixes

fix(schema): Fields with json:",omitempty" are no longer marked as required even if validate:"required" is present.
feat(schema): Added Nullable, ReadOnly, WriteOnly, Deprecated, MinItems, MaxItems, UniqueItems, AllOf, OneOf, AnyOf fields to schema.Schema and full conversion support in convertSchema().
fix(schema): Added special handling for time.Duration → {format:"duration"}, []byte → {format:"byte"}, uuid.UUID → {format:"uuid"}.
fix(schema): json:",omitempty" (empty name part) now correctly falls back to the Go field name.

Low Severity Fixes

fix(openapi): buildParamsFromStruct now prefers location-specific tags (query tag for query params, path tag for path params) before falling back to generic tags.
feat(openapi): Request body schemas now include an auto-generated example field built from struct field tags and type defaults.

v1.0.0

Initial release of open-swag-go.

5 framework adapters: Chi, Gin, Echo, Fiber, net/http
Authentication playground with Bearer, Basic, API Key, Cookie, and OAuth2 support
Try-it console with environment management and request history
Auto-generated code snippets in curl, JavaScript, Go, and Python
Version diffing with breaking change detection and migration guides
Schema generation from Go structs using standard tags
Theming with Scalar UI (purple, blue, green, light themes + dark mode)
Docs page authentication with basic auth or API key
Smart example generation from struct field names and tags

On this page