openapi

Okapi OpenAPI Documentation

Okapi generates OpenAPI from your routes and serves three interactive UIs. The default document is OpenAPI 3.1 (JSON Schema 2020-12); a 3.0 view is served alongside for legacy consumers.

Default Endpoints

Route	Content
/docs	Selected UI (Swagger UI by default)
/swagger	Swagger UI
/redoc	ReDoc
/scalar	Scalar API Reference
/openapi.json	OpenAPI 3.1 spec (JSON)
/openapi.yaml	OpenAPI 3.1 spec (YAML)
/openapi-3.0.json	OpenAPI 3.0 spec (JSON)
/openapi-3.0.yaml	OpenAPI 3.0 spec (YAML)

Enabling Docs

o := okapi.Default()                // docs ON by default
o := okapi.New().WithOpenAPIDocs()  // opt in for New()
o.WithOpenAPIDisabled()             // disable (routes return 404)

The document is rebuilt lazily, so route changes (enable/disable, new webhooks) show up on the next request.

Choosing the UI

o.WithOpenAPIDocs(okapi.OpenAPI{
    Title: "My API",
    UI:    okapi.ScalarUI, // SwaggerUI (default) | RedocUI | ScalarUI
})

// Chainable equivalent
o := okapi.New().WithOpenAPIDocs().WithDocUI(okapi.ScalarUI)
// Or as an option: okapi.New(okapi.WithDocUI(okapi.RedocUI))

Every UI stays reachable at its own route. StrictDocUI: true registers only /docs; the per-UI routes then 404:

o.WithOpenAPIDocs(okapi.OpenAPI{
    Title:       "My API",
    UI:          okapi.ScalarUI,
    StrictDocUI: true,
})

Full Configuration

o.WithOpenAPIDocs(okapi.OpenAPI{
    Title:          "Example API",
    Version:        "1.0.0",
    Summary:        "Short summary",            // OpenAPI >= 3.1 only
    Description:    "Example API description",
    TermsOfService: "https://example.com/terms",
    Favicon:        "https://example.com/favicon.png", // favicon for the doc UIs
    Servers:        okapi.Servers{{URL: "https://api.example.com", Description: "Production"}},
    License:        okapi.License{Name: "Apache 2.0", Identifier: "Apache-2.0"}, // SPDX → 3.1 only
    Contact:        okapi.Contact{Name: "API Support", Email: "[email protected]", URL: "https://example.com"},
    ExternalDocs:   &okapi.ExternalDocs{URL: "https://docs.example.com", Description: "Docs"},
    SecuritySchemes: okapi.SecuritySchemes{
        {Name: "basicAuth", Type: "http", Scheme: "basic"},
        {Name: "bearerAuth", Type: "http", Scheme: "bearer", BearerFormat: "JWT"},
        {Name: "apiKey", Type: "apiKey", In: "header", Description: "API key header"},
        {
            Name: "OAuth2", Type: "oauth2",
            Flows: &okapi.OAuthFlows{
                AuthorizationCode: &okapi.OAuthFlow{
                    AuthorizationURL: "https://auth.example.com/authorize",
                    TokenURL:         "https://auth.example.com/token",
                    RefreshURL:       "https://auth.example.com/refresh",
                    Scopes:           map[string]string{"read": "Read access", "write": "Write access"},
                },
            },
        },
    },
})