Migrating from v1.0.x to v1.1.1

v1.1.0 and v1.1.1 are both fully backwards-compatible — no public API signatures changed, and existing endpoint definitions continue to compile. v1.1.0 ships 12 schema-generation fixes; v1.1.1 makes example values opt-in for cleaner specs. Update by running:

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

What Changed

Schema Generation Fixes

Embedded struct promotion — Embedded (anonymous) struct fields now have their properties promoted into the parent schema, matching Go's field promotion behavior.

// Before v1.1.0: Embedded fields were ignored
// After v1.1.0: Embedded fields are promoted
type Timestamps struct {
    CreatedAt time.Time `json:"created_at"`
    UpdatedAt time.Time `json:"updated_at"`
}
 
type User struct {
    Timestamps // Now correctly promoted into User's schema
    ID   int64  `json:"id"`
}

Map types generate additionalProperties — map[K]V types now correctly produce {"type":"object","additionalProperties":{...}}.

interface/any produces empty schema — Fields typed as interface{} or any now generate an empty schema {} (accepts any value) instead of {"type":"object"}.

omitempty overrides required — Fields with json:",omitempty" are no longer marked as required, even if validate:"required" is set.

New schema fields — ReadOnly, WriteOnly, Deprecated, MinItems, MaxItems, UniqueItems, AllOf, OneOf, AnyOf, and AdditionalProperties are now supported on the Schema struct.

Special type handling — time.Duration → {format:"duration"}, []byte → {format:"byte"}, uuid.UUID → {format:"uuid"}.

$ref preservation — $ref pointers are no longer silently dropped during schema conversion.

Example Generation Fixes

Type-coerced examples — Example tag values are now coerced to the correct type. example:"42" on an int64 field produces the integer 42 in the spec, not the string "42".

Request body auto-examples — Request body schemas now automatically include a generated example field built from struct tags and type defaults.

Parameter Handling Fixes

Location-specific tags preferred — ParametersFromStruct now prefers query tags for query params and path tags for path params before falling back to json tags.

Server Configuration Fixes

Port conversion fix — CommonServers.Localhost() and LocalhostServer() now correctly convert port numbers to strings (previously used invalid string(rune(port)) conversion). If you used openswag.LocalhostServer(port) or CommonServers.Localhost(port) on v1.0.0, the URL was silently broken — upgrading is strongly recommended.

What Changed in v1.1.1

Examples are now opt-in. v1.1.0 auto-generated placeholder example values for every primitive field ("string", 0, false, …) even when no example tag was set. v1.1.1 removes that behavior — example values appear only where you set example:"...". The result is a cleaner Scalar UI without placeholder noise.

If your spec was relying on those placeholders to populate the rendered docs, add explicit example:"..." tags to the fields you want shown:

// Before (v1.1.0 would auto-fill these in the spec)
type CreateUserRequest struct {
    Name  string `json:"name"`
    Email string `json:"email"`
}
 
// After (v1.1.1 — be explicit about which examples you want)
type CreateUserRequest struct {
    Name  string `json:"name"  example:"Jane Doe"`
    Email string `json:"email" example:"jane@example.com"`
}

example:"null" literal — Setting example:"null" on any field type now produces a real JSON null in the spec (previously this only worked for slices and maps). Use it to document nullable fields.

Typed-nil example bug fixed — Stray "example": null entries no longer leak into request body schemas when no example is provided.

Migration Checklist

• Run go get github.com/gopackx/open-swag-go@v1.1.1
• Review any interface{}/any fields — they now produce empty schemas instead of {"type":"object"} (v1.1.0)
• Review fields with both omitempty and validate:"required" — omitempty now takes precedence (v1.1.0)
• Verify embedded struct schemas are promoted correctly (v1.1.0)
• Check that example values in your spec now have correct types (integers, floats, booleans) (v1.1.0)
• Add explicit example:"..." tags to any fields where you previously relied on auto-generated placeholders (v1.1.1)
• If you used openswag.LocalhostServer(port) on v1.0.0, regenerate your spec — the URL output is now correct
• Run your test suite to confirm no regressions

Migrating from v0.x to v1.0

Config Structure

The Config struct was restructured to group related settings.

Before

docs := openswag.New(openswag.Config{
    Title:       "My API",
    Version:     "1.0.0",
    BasePath:    "/api",
    DocsPath:    "/docs",
    Theme:       "purple",
    DarkMode:    true,
})

After

docs := openswag.New(openswag.Config{
    Info: openswag.Info{
        Title:   "My API",
        Version: "1.0.0",
    },
    BasePath: "/api",
    DocsPath: "/docs",
    UIConfig: openswag.UIConfig{
        Theme:    "purple",
        DarkMode: true,
    },
})

Endpoint Definitions

Endpoints now use struct-based parameter definitions instead of inline strings.

Before

docs.AddEndpoint(openswag.Endpoint{
    Method:  "GET",
    Path:    "/users/{id}",
    Summary: "Get user",
    Params: map[string]string{
        "id": "string",
    },
    Response: `{"id": "string", "name": "string"}`,
})

After

type GetUserParams struct {
    ID string `json:"id" swagger:"path,required" description:"User ID"`
}
 
type User struct {
    ID   string `json:"id" example:"usr_123"`
    Name string `json:"name" example:"Jane Doe"`
}
 
docs.AddEndpoint(openswag.Endpoint{
    Method:     "GET",
    Path:       "/users/{id}",
    Summary:    "Get user",
    Parameters: openswag.ParamsFrom[GetUserParams](),
    Response: openswag.Response{
        Status:      200,
        Description: "User found",
        Body:        openswag.BodyFrom[User](),
    },
})

Authentication Schemes

Auth schemes moved from inline config to the pkg/auth package.

Before

docs := openswag.New(openswag.Config{
    Auth: openswag.Auth{
        Type:   "bearer",
        Scheme: "JWT",
    },
})

After

import "github.com/gopackx/open-swag-go/pkg/auth"
 
bearerAuth := auth.BearerAuth("jwt", "JWT Authentication")
 
docs := openswag.New(openswag.Config{
    Info: openswag.Info{
        Title:   "My API",
        Version: "1.0.0",
    },
    SecuritySchemes: []auth.Scheme{bearerAuth},
})

Framework Adapter Mounting

Adapter mounting functions were unified across all frameworks.

Before

// Chi
r.Handle("/docs/*", docs.Handler())
 
// Gin
r.Any("/docs/*any", gin.WrapH(docs.Handler()))

After

// Chi
import chiadapter "github.com/gopackx/open-swag-go/adapters/chi"
chiadapter.Mount(r, "/docs", docs)
 
// Gin
import ginadapter "github.com/gopackx/open-swag-go/adapters/gin"
ginadapter.Mount(r, "/docs", docs)

Schema Generation Tags

The swagger struct tag syntax was updated for clarity.

Before

type Product struct {
    ID    int     `json:"id" swagger:"integer,required"`
    Price float64 `json:"price" swagger:"number,format=double"`
}

After

type Product struct {
    ID    int     `json:"id" swagger:"required" format:"int64"`
    Price float64 `json:"price" format:"double" example:"29.99"`
}

Try-It Console

Console configuration moved to a dedicated package.

Before

docs := openswag.New(openswag.Config{
    Console: true,
    ConsoleTheme: "dark",
})

After

import "github.com/gopackx/open-swag-go/pkg/tryit"
 
console := tryit.NewConsoleConfig(
    tryit.WithEnabled(true),
    tryit.WithTheme("dark"),
    tryit.WithHistory(true),
)
 
docs := openswag.New(openswag.Config{
    Info: openswag.Info{
        Title:   "My API",
        Version: "1.0.0",
    },
    ConsoleConfig: console,
})

Migration Checklist

• Update Config to use nested Info and UIConfig structs
• Convert inline parameter definitions to struct-based ParamsFrom[T]()
• Move auth configuration to pkg/auth package
• Update framework adapter mounting to use adapter-specific Mount() functions
• Update struct tags to new swagger tag syntax
• Migrate console configuration to pkg/tryit package
• Run go vet and fix any compilation errors
• Regenerate your OpenAPI spec and verify output