Code Snippets

The snippets feature generates ready-to-use code examples for every endpoint in your docs. Visitors see a tabbed panel with curl, JavaScript, Go, Python, and PHP snippets they can copy and paste directly into their projects.

SnippetConfig

SnippetConfig controls snippet generation and is passed to the top-level Config via the Console field.

snippet_config.go

type SnippetConfig struct {
	Enabled   bool       // Enable code snippet generation
	Languages []Language // Which languages to generate snippets for
	Templates map[Language]string // Custom templates per language (optional)
}

Supported languages

The Language type defines the five built-in languages:

languages.go

const (
	LangCurl       Language = "curl"
	LangJavaScript Language = "javascript"
	LangGo         Language = "go"
	LangPython     Language = "python"
	LangPHP        Language = "php"
)

Enabling Snippets

Minimal setup

Enable snippets with all five languages using the defaults:

basic_snippets.go

import (
	openswag "github.com/andrianprasetya/open-swag-go"
	"github.com/andrianprasetya/open-swag-go/pkg/tryit/snippets"
)
 
cfg := openswag.Config{
	Title:   "My API",
	Version: "1.0.0",
	Console: tryit.ConsoleConfig{
		Enabled: true,
		Snippets: snippets.SnippetConfig{
			Enabled: true,
		},
	},
}

When Languages is empty, all five languages are included by default.

Selecting specific languages

Show only the languages your audience needs:

select_languages.go

snippetCfg := snippets.SnippetConfig{
	Enabled: true,
	Languages: []snippets.Language{
		snippets.LangCurl,
		snippets.LangJavaScript,
		snippets.LangPython,
	},
}

Example Output

Given a POST /users endpoint with a JSON body, the snippet generator produces the following for each language:

curl

curl_output

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"name": "Alice", "email": "alice@example.com"}'

JavaScript

javascript_output

const response = await fetch("https://api.example.com/users", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <token>",
  },
  body: JSON.stringify({
    name: "Alice",
    email: "alice@example.com",
  }),
});
 
const data = await response.json();

Go

go_output

body := map[string]string{
	"name":  "Alice",
	"email": "alice@example.com",
}
jsonBody, _ := json.Marshal(body)
 
req, _ := http.NewRequest("POST", "https://api.example.com/users", bytes.NewBuffer(jsonBody))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer <token>")
 
resp, err := http.DefaultClient.Do(req)

Python

python_output

import requests
 
response = requests.post(
    "https://api.example.com/users",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer <token>",
    },
    json={"name": "Alice", "email": "alice@example.com"},
)
 
data = response.json()

PHP

php_output

$ch = curl_init("https://api.example.com/users");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Authorization: Bearer <token>",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "name" => "Alice",
    "email" => "alice@example.com",
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
 
$response = curl_exec($ch);
curl_close($ch);

Custom Templates

Override the default snippet template for any language. Templates use Go text/template syntax with access to the endpoint's method, URL, headers, and body.

custom_templates.go

snippetCfg := snippets.SnippetConfig{
	Enabled: true,
	Templates: map[snippets.Language]string{
		snippets.LangCurl: `curl -X {{.Method}} {{.URL}}{{range $k, $v := .Headers}} \
  -H "{{$k}}: {{$v}}"{{end}}{{if .Body}} \
  -d '{{.Body}}'{{end}}`,
	},
}

Template variables

Variable	Type	Description
`.Method`	`string`	HTTP method (`GET`, `POST`, etc.)
`.URL`	`string`	Full request URL including path
`.Headers`	`map[string]string`	Request headers
`.Body`	`string`	JSON-encoded request body (empty for GET)
`.ContentType`	`string`	Content-Type header value

Full Example

A complete setup with the try-it console, selected languages, and a custom curl template:

full_snippets.go

package main
 
import (
	openswag "github.com/andrianprasetya/open-swag-go"
	"github.com/andrianprasetya/open-swag-go/pkg/tryit"
	"github.com/andrianprasetya/open-swag-go/pkg/tryit/snippets"
	"github.com/andrianprasetya/open-swag-go/adapters/nethttp"
	"net/http"
)
 
func main() {
	snippetCfg := snippets.SnippetConfig{
		Enabled: true,
		Languages: []snippets.Language{
			snippets.LangCurl,
			snippets.LangJavaScript,
			snippets.LangGo,
			snippets.LangPython,
		},
	}
 
	cfg := openswag.Config{
		Title:   "My API",
		Version: "1.0.0",
		Console: tryit.ConsoleConfig{
			Enabled:  true,
			Snippets: snippetCfg,
		},
	}
 
	endpoints := []openswag.Endpoint{
		{
			Method:  "GET",
			Path:    "/users",
			Summary: "List users",
			Tags:    []string{"Users"},
			Responses: []openswag.Response{
				{StatusCode: 200, Description: "User list", ContentType: "application/json"},
			},
		},
		{
			Method:  "POST",
			Path:    "/users",
			Summary: "Create user",
			Tags:    []string{"Users"},
			RequestBody: &openswag.RequestBody{
				ContentType: "application/json",
				Description: "User to create",
			},
			Responses: []openswag.Response{
				{StatusCode: 201, Description: "Created user", ContentType: "application/json"},
			},
		},
	}
 
	docs := openswag.New(cfg, endpoints...)
	mux := http.NewServeMux()
	nethttp.Mount(mux, "/docs", docs)
 
	http.ListenAndServe(":8080", mux)
}

On this page