Try-It Package

pkg/tryit powers the interactive "Try It" console in the docs UI. It lets users send real HTTP requests, manage environment variables, view request history, and generate code snippets.

import "github.com/gopackx/open-swag-go/pkg/tryit"

ConsoleConfig

Top-level configuration for the try-it console.

type ConsoleConfig struct {
    Enabled          bool              // Enable the try-it console
    DefaultServer    string            // Default server URL
    RequestTimeout   int               // Request timeout in milliseconds
    ShowCodeSnippets bool              // Show generated code snippets
    EnabledLanguages []string          // Snippet languages to display
    CustomHeaders    map[string]string // Headers added to every request
    ProxyURL         string            // Proxy URL for requests
    CORSProxy        bool              // Enable a CORS proxy for browser requests
}

Constructor and options

func DefaultConsoleConfig() ConsoleConfig
func NewConsole(opts ...ConsoleOption) *ConsoleConfig
 
func WithTimeout(ms int) ConsoleOption
func WithDefaultServer(url string) ConsoleOption
func WithLanguages(languages ...string) ConsoleOption
func WithCustomHeader(key, value string) ConsoleOption
func WithProxy(url string) ConsoleOption
func WithCORSProxy(enabled bool) ConsoleOption
func DisableSnippets() ConsoleOption
func Disable() ConsoleOption

console := tryit.NewConsole(
    tryit.WithDefaultServer("https://api.example.com"),
    tryit.WithTimeout(15000),
    tryit.WithCustomHeader("X-Request-Source", "docs"),
    tryit.WithLanguages("curl", "javascript", "go", "python"),
)

Snippet generators ship for curl, JavaScript, Go, and Python. "php" may appear in the default language list but has no generator, so no PHP snippet is produced.

Environment

A named set of variables that can be switched in the console.

type Environment struct {
    Name      string            // Display name, e.g. "Staging"
    Variables map[string]string // Key-value pairs
    IsActive  bool              // Whether this is the active environment
}
 
type EnvironmentConfig struct {
    Enabled    bool
    Storage    string
    StorageKey string
}

EnvironmentManager

Manages multiple environments and interpolates variable references in requests.

func DefaultEnvironmentConfig() EnvironmentConfig
func NewEnvironmentManager(config EnvironmentConfig) *EnvironmentManager
func CreateDefaultEnvironments() []Environment

Methods

func (m *EnvironmentManager) Add(env Environment)
func (m *EnvironmentManager) Get() []Environment
func (m *EnvironmentManager) GetByName(name string) (Environment, bool)
func (m *EnvironmentManager) SetActive(name string) bool
func (m *EnvironmentManager) GetActive() (Environment, bool)
func (m *EnvironmentManager) Delete(name string) bool
func (m *EnvironmentManager) Update(name string, variables map[string]string) bool
func (m *EnvironmentManager) Interpolate(input string) string
func (m *EnvironmentManager) ToJSON() (string, error)
func (m *EnvironmentManager) FromJSON(data string) error
func (m *EnvironmentManager) GetConfig() EnvironmentConfig

Interpolate replaces {{variable}} placeholders with values from the active environment.

mgr := tryit.NewEnvironmentManager(tryit.DefaultEnvironmentConfig())
mgr.Add(tryit.Environment{
    Name:      "Staging",
    Variables: map[string]string{"base_url": "https://staging.api.com"},
})
mgr.SetActive("Staging")
url := mgr.Interpolate("{{base_url}}/users") // "https://staging.api.com/users"

History

Stores and retrieves past requests made through the console.

type HistoryConfig struct {
    Enabled    bool
    MaxEntries int
    Storage    string
    StorageKey string
}
 
type HistoryEntry struct {
    ID          string
    Timestamp   time.Time
    Method      string
    URL         string
    Path        string
    Headers     map[string]string
    Body        string
    StatusCode  int
    Response    string
    Duration    int64 // milliseconds
    OperationID string
}

func DefaultHistoryConfig() HistoryConfig
func NewHistory(config HistoryConfig) *History

Methods

func (h *History) Add(entry HistoryEntry)
func (h *History) Get() []HistoryEntry
func (h *History) GetByID(id string) (HistoryEntry, bool)
func (h *History) Clear()
func (h *History) Delete(id string) bool
func (h *History) ToJSON() (string, error)
func (h *History) FromJSON(data string) error
func (h *History) GetConfig() HistoryConfig

hist := tryit.NewHistory(tryit.DefaultHistoryConfig())
hist.Add(tryit.HistoryEntry{
    Method:     "GET",
    URL:        "https://api.example.com/users",
    StatusCode: 200,
})
entries := hist.Get()

Snippets sub-package

pkg/tryit/snippets generates ready-to-use code snippets from a request definition.

import "github.com/gopackx/open-swag-go/pkg/tryit/snippets"

Request

type Request struct {
    Method      string
    URL         string
    Headers     map[string]string
    Body        string
    QueryParams map[string]string
}

Generator and Manager

Generator is an interface; Manager holds the registered generators.

type Generator interface {
    Generate(req Request) string
    Language() string
    DisplayName() string
}
 
func NewManager() *Manager // registers curl, javascript, go, python
 
func (m *Manager) Register(gen Generator)
func (m *Manager) Generate(language string, req Request) (string, bool)
func (m *Manager) GenerateAll(req Request) map[string]string
func (m *Manager) Languages() []string
func (m *Manager) GetGenerator(language string) (Generator, bool)

Usage

mgr := snippets.NewManager()
 
snippet, ok := mgr.Generate("curl", snippets.Request{
    Method:  "POST",
    URL:     "https://api.example.com/users",
    Headers: map[string]string{"Content-Type": "application/json"},
    Body:    `{"name": "Alice"}`,
})
if ok {
    fmt.Println(snippet)
}
 
// Or generate every language at once:
all := mgr.GenerateAll(snippets.Request{Method: "GET", URL: "https://api.example.com/users"})

On this page