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{
    Info: openswag.Info{
    	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, docs, "/api-docs")

How do I change the UI theme?

Set the Theme field in UIConfig:

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

The value is passed to Scalar unchanged, so use any theme name supported by the Scalar version you load. The default is purple. See Theming.

Can I use multiple authentication schemes?

Yes. Reference each scheme by name in an endpoint's Security, then register the schemes on the built spec:

docs.Add(openswag.Endpoint{
    Method:   "GET",
    Path:     "/users/me",
    Security: []string{openswag.SecurityBearerAuth, openswag.SecurityApiKey},
    // ...
})
 
openapi := docs.BuildSpec()
openapi.AddSecurityScheme("bearerAuth", &spec.SecurityScheme{
    Type: "http", Scheme: "bearer", BearerFormat: "JWT",
})
openapi.AddSecurityScheme("apiKeyAuth", &spec.SecurityScheme{
    Type: "apiKey", Name: "X-API-Key", In: "header",
})

The latest version is v1.3.0. It changes the generated spec (named components.schemas, 3.1 nullable type arrays, operationId) and removes packages that were never used by the runtime, so read the Changelog and Migration Guide before upgrading.

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

Usage

How do I add an endpoint?

Use docs.Add() with an Endpoint struct (or docs.AddAll(...) for several):

docs.Add(openswag.Endpoint{
    Method:  "GET",
    Path:    "/api/users",
    Summary: "List users",
    Tags:    []string{"Users"},
    Responses: openswag.Responses{
        200: {Description: "User list"},
    },
})

Can I generate the spec without running a server?

Yes. Use docs.SpecJSON() to get the spec as JSON bytes:

data, _ := docs.SpecJSON()
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.Add() (or docs.AddAll()) 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.

If the embedded type is unexported (for example type base struct{...} embedded as base), its fields were still dropped before v1.3.0. v1.3.0+ promotes them the way encoding/json does: a field declared on the outer struct shadows a promoted one with the same name, and a json name on the embedded field (base `json:"base"` ) makes it a nested object instead.

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"}.