Quick Start

This guide walks you through a complete, runnable Go program that serves interactive API documentation using open-swag-go and the standard library net/http router.

The Full Program

Create a file called main.go and paste the following:

main.go

package main
 
import (
	"fmt"
	"net/http"
 
	openswag "github.com/gopackx/open-swag-go"
)
 
// Pet is the response model returned by the API.
type Pet struct {
	ID   int    `json:"id" example:"1"`
	Name string `json:"name" example:"Buddy"`
	Kind string `json:"kind" example:"dog"`
}
 
func main() {
	// 1. Configure your API metadata
	cfg := openswag.Config{
		Info: openswag.Info{
			Title:       "Pet Store API",
			Version:     "1.0.0",
			Description: "A simple pet store to demo open-swag-go.",
		},
		Servers: []openswag.Server{
			{URL: "http://localhost:8080"},
		},
	}
 
	// 2. Define your endpoints
	endpoints := []openswag.Endpoint{
		{
			Method:      "GET",
			Path:        "/pets",
			Summary:     "List all pets",
			Description: "Returns every pet in the store.",
			Tags:        []string{"Pets"},
			Responses: openswag.Responses{
				200: openswag.Response("A list of pets", []Pet{}),
			},
		},
		{
			Method:      "POST",
			Path:        "/pets",
			Summary:     "Add a pet",
			Description: "Creates a new pet in the store.",
			Tags:        []string{"Pets"},
			RequestBody: openswag.BodyWithDesc("Pet object to create", Pet{}),
			Responses: openswag.Responses{
				201: openswag.Response("Pet created successfully", Pet{}),
			},
		},
	}
 
	// 3. Create the docs instance, register endpoints, and mount it
	docs := openswag.New(cfg)
	docs.AddAll(endpoints...)
 
	mux := http.NewServeMux()
	docs.Mount(mux, "/docs")
 
	fmt.Println("Docs available at http://localhost:8080/docs")
	http.ListenAndServe(":8080", mux)
}

Step-by-Step Walkthrough

1. Configure API metadata

openswag.Config holds the top-level information that appears in the generated OpenAPI spec — title, version, description, and server URLs.

cfg := openswag.Config{
	Info: openswag.Info{
		Title:       "Pet Store API",
		Version:     "1.0.0",
		Description: "A simple pet store to demo open-swag-go.",
	},
	Servers: []openswag.Server{
		{URL: "http://localhost:8080"},
	},
}

Each openswag.Endpoint describes a single API operation. You specify the HTTP method, path, summary, tags, request body, and responses. Open Swag Go turns these into a valid OpenAPI 3.x spec behind the scenes.

endpoints := []openswag.Endpoint{
	{
		Method:  "GET",
		Path:    "/pets",
		Summary: "List all pets",
		// ...
	},
	{
		Method:  "POST",
		Path:    "/pets",
		Summary: "Add a pet",
		// ...
	},
}

3. Mount and serve

openswag.New creates a *Docs instance from your config. Register endpoints with docs.AddAll(...) (or docs.Add(...) one at a time), then call the docs.Mount method to attach the docs UI to any net/http mux at the path you choose.

docs := openswag.New(cfg)
docs.AddAll(endpoints...)
 
mux := http.NewServeMux()
docs.Mount(mux, "/docs")
 
http.ListenAndServe(":8080", mux)

Run It

go run main.go

Open http://localhost:8080/docs in your browser. You should see a Scalar-powered docs UI with your two pet endpoints listed and ready to explore.

Next Steps

Add more features — authentication schemes, try-it console, code snippets, and theming. See the Features section.
Use a framework adapter — if you're on Chi, Gin, Echo, or Fiber, check the Adapters guide for framework-specific mounting.
Browse real-world examples — the Examples section walks through progressively complex setups.