FAQ | OPEN SWAGGO

Installation

How do I install it?

go get github.com/gopackx/open-swag-go

Do I need to install framework adapters separately?

Yes. Each adapter is a separate import:

import chiadapter "github.com/gopackx/open-swag-go/adapters/chi"

The adapters are included in the same module, so go get pulls them all in — you just import the one you need.

Configuration

What's the minimum configuration to get started?

docs := openswag.New(openswag.Config{
    Title:   "My API",
    Version: "1.0.0",
})

Then mount it on your router and add endpoints.

Can I serve docs at a custom path?

Yes, pass the path when mounting:

chiadapter.Mount(r, "/api-docs", docs)

How do I change the UI theme?

Set the Theme field in UIConfig:

docs := openswag.New(openswag.Config{
    Title:   "My API",
    Version: "1.0.0",
    UIConfig: openswag.UIConfig{
        Theme:    "blue",
        DarkMode: true,
    },
})

Available themes: purple, blue, green, light.

Can I use multiple authentication schemes?

Yes. Pass multiple schemes to SecuritySchemes:

docs := openswag.New(openswag.Config{
    SecuritySchemes: []auth.Scheme{
        auth.BearerAuth("jwt", "JWT Authentication"),
        auth.APIKeyAuth("api-key", "API Key", "X-API-Key", "header"),
    },
})

The latest version is v1.1.1. It builds on v1.1.0 (12 schema-generation fixes) and makes example values opt-in for cleaner specs. All changes since v1.0.0 are backwards-compatible. See the Changelog and Migration Guide for details.

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

Usage

How do I add an endpoint?

Use docs.AddEndpoint() with an Endpoint struct:

docs.AddEndpoint(openswag.Endpoint{
    Method:  "GET",
    Path:    "/api/users",
    Summary: "List users",
    Tags:    []string{"Users"},
})

Can I generate the spec without running a server?

Yes. Use docs.GenerateSpec() to get the spec as a Go struct, then marshal it to JSON:

spec, _ := docs.GenerateSpec()
data, _ := json.MarshalIndent(spec, "", "  ")
os.WriteFile("openapi.json", data, 0644)

Does open-swag-go support OpenAPI 3.1?

open-swag-go generates OpenAPI 3.0.3 specs by default. OpenAPI 3.1 support is planned for a future release.

Can I use open-swag-go with a framework not listed in the adapters?

Yes. Use the net/http adapter, which works with any framework that supports http.Handler:

import nethttpadapter "github.com/gopackx/open-swag-go/adapters/nethttp"
 
nethttpadapter.Mount(mux, "/docs", docs)

How do I hide certain endpoints from the docs?

Only endpoints you explicitly register with docs.AddEndpoint() appear in the spec. If you don't register an endpoint, it won't be documented.

Can I generate TypeScript types from my spec?

Yes. Export your spec to a file and use tools like openapi-typescript, openapi-fetch, or orval. See the TypeScript Types guide for details.

Why are my example values showing as strings in the spec?

If you're on v1.0.x, example tag values were always stored as strings regardless of the field type. Upgrade to v1.1.0 where example:"42" on an int64 field correctly produces the integer 42 in the spec.

Why are embedded struct fields missing from my schema?

Embedded (anonymous) struct fields are supported in v1.1.0+. If you're on v1.0.x, embedded fields are silently ignored. Upgrade to v1.1.0 to get automatic field promotion.

How are `map` types represented in the schema?

In v1.1.0+, map[string]T generates {"type":"object","additionalProperties":{...}} where the value schema describes T. In v1.0.x, map types were not correctly handled.

How are `interface{}`/`any` fields represented?

In v1.1.0+, interface{} and any fields produce an empty schema {} (accepts any JSON value). In v1.0.x, they incorrectly produced {"type":"object"}.