OPEN SWAG GO
Guides

Migrating from v1.0.x to v1.1.0

v1.1.0 is fully backwards-compatible — no public API signatures changed. All fixes are additive struct fields and behavior corrections. Update by running:

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

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).

Migration Checklist

  • Run go get github.com/gopackx/open-swag-go@v1.1.0
  • Review any interface{}/any fields — they now produce empty schemas instead of {"type":"object"}
  • Review fields with both omitempty and validate:"required" — omitempty now takes precedence
  • Verify embedded struct schemas are promoted correctly
  • Check that example values in your spec now have correct types (integers, floats, booleans)
  • 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

TypeScript Type Generation

Previous Page

Changelog

Next Page

On this page

Migrating from v1.0.x to v1.1.0What ChangedSchema Generation FixesExample Generation FixesParameter Handling FixesServer Configuration FixesMigration ChecklistMigrating from v0.x to v1.0Config StructureBeforeAfterEndpoint DefinitionsBeforeAfterAuthentication SchemesBeforeAfterFramework Adapter MountingBeforeAfterSchema Generation TagsBeforeAfterTry-It ConsoleBeforeAfterMigration Checklist