Core Package

type Config struct {
    Info     Info       // API metadata (title, version, description)
    Servers  []Server   // Server URLs shown in the docs UI
    Tags     []Tag      // Logical groupings for endpoints
    UI       UIConfig   // Scalar UI appearance settings
    Auth     AuthConfig // Security schemes exposed under components.securitySchemes
    DocsAuth *DocsAuth  // Optional password/API-key protection for the docs page
    InlineSchemas bool  // Inline every struct instead of emitting components.schemas (v1.3.0+)
}

func New(cfg Config) *Docs

type Docs struct {
    // unexported fields
}
 
func (d *Docs) Add(endpoint Endpoint)                       // Register one endpoint
func (d *Docs) AddAll(endpoints ...Endpoint)                // Register multiple endpoints
func (d *Docs) Validate() error                             // Report invalid endpoint definitions (v1.3.0+)
func (d *Docs) Mount(mux *http.ServeMux, basePath string)   // Serve UI + spec on a ServeMux
func (d *Docs) Handler() http.HandlerFunc                   // Handler that serves the docs UI
func (d *Docs) SpecHandler() http.HandlerFunc               // Handler that serves the raw OpenAPI JSON
func (d *Docs) SpecJSON() ([]byte, error)                   // The OpenAPI spec as JSON bytes
func (d *Docs) BuildSpec() *spec.OpenAPI                    // The compiled spec object
func (d *Docs) GetUIConfig() (string, error)                // Serialized UI config (advanced)

docs := openswag.New(cfg)
docs.AddAll(endpoints...)
if err := docs.Validate(); err != nil {
    log.Fatal(err)
}
 
// Serve with net/http
mux := http.NewServeMux()
docs.Mount(mux, "/docs")
http.ListenAndServe(":8080", mux)

type Endpoint struct {
    Method      string            // GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, TRACE
    Path        string            // "/users/{id}"; "/users/:id", "/files/*path" are normalised
    OperationID string            // Overrides the generated operationId (v1.3.0+)
    Summary     string            // Short one-line description
    Description string            // Detailed explanation (Markdown supported)
    Tags        []string          // Grouping tags for the sidebar
    Parameters  []Parameter       // Path, query, and header parameters (manual)
    QueryParams interface{}       // Struct whose fields become query params (form/description/example tags)
    PathParams  interface{}       // Struct whose fields become path params (param tag)
    RequestBody *RequestBody      // Request body (nil for GET/DELETE)
    Responses   Responses         // map[int]ResponseSpec keyed by HTTP status
    Security    []string          // Security scheme names applied to this endpoint
    Deprecated  bool              // Mark the endpoint as deprecated
}
 
// Responses is a convenience alias used in endpoint literals.
type Responses = map[int]ResponseSpec

type Parameter struct {
    Name        string       // Parameter name, e.g. "id"
    In          string       // Location: "path", "query", "header", or "cookie"
    Description string       // Human-readable description
    Required    bool         // Whether the parameter is mandatory
    Schema      *spec.Schema // Parameter schema (e.g. spec.NewSchema("string"))
    Example     interface{}  // Optional example value
}

type RequestBody struct {
    Description string      // What the body represents
    ContentType string      // MIME type, e.g. "application/json", "multipart/form-data"
    Required    bool        // Whether the body is mandatory
    Schema      interface{} // Go struct for schema generation
}

type ResponseSpec struct {
    Description string      // What this response means
    Schema      interface{} // Go struct for schema generation (optional)
}
 
// Response builds a ResponseSpec. Pass the schema as the second argument,
// or omit it for empty responses (e.g. 204 No Content).
func Response(description string, schema ...interface{}) ResponseSpec

Responses: openswag.Responses{
    200: openswag.Response("A list of pets", []Pet{}),
    204: openswag.Response("Deleted"),
    404: openswag.Response("Not found", ErrorResponse{}),
},

// JSON body (Required: true, ContentType: "application/json")
openswag.Body(CreateUserRequest{})
 
// JSON body with a description
openswag.BodyWithDesc("Pet object to create", Pet{})
 
// multipart/form-data — for file uploads / HTML forms
openswag.FormBody(UploadRequest{})
 
// application/x-www-form-urlencoded
openswag.FormURLEncodedBody(LoginForm{})

openswag.PathParam("id", "User ID")                          // required path string
openswag.QueryParam("include", "Related resources")           // optional query string
openswag.RequiredQueryParam("filter", "Required filter")      // required query string
openswag.HeaderParam("X-Request-ID", "Request tracking ID")   // optional header
openswag.CookieParam("session", "Session cookie")             // optional cookie

type AuthConfig struct {
    PersistCredentials bool         // No runtime effect: not passed to the docs UI (see below)
    Schemes            []AuthScheme // Schemes exposed under components.securitySchemes
}
 
type AuthScheme struct {
    Name         string // ID referenced from Endpoint.Security
    Type         string // "http", "apiKey", "oauth2", "openIdConnect"
    Scheme       string // "bearer" / "basic" when Type == "http"
    BearerFormat string // Hint for http+bearer (e.g. "JWT")
    In           string // "header" / "query" / "cookie" when Type == "apiKey"
    ParamName    string // Header/query/cookie name carrying the credential
    Description  string
}

Auth: openswag.AuthConfig{
    Schemes: []openswag.AuthScheme{
        openswag.BearerAuth(openswag.SecurityBearerAuth),
        openswag.APIKeyAuth("apiKey", "X-API-Key"),
        openswag.BasicAuth(openswag.SecurityBasicAuth),
        openswag.CookieAuth(openswag.SecurityCookieAuth, "session_id"),
    },
},

type UIConfig struct {
    Theme              string // Scalar theme name, passed to Scalar as-is (default "purple")
    DarkMode           bool   // Enable dark mode by default
    Layout             string // Scalar layout, passed as-is (default "modern")
    ShowSidebar        bool   // Show the navigation sidebar
    SidebarSearch      bool   // Deprecated: has no effect (v1.3.0+)
    TagGrouping        bool   // Deprecated: has no effect (v1.3.0+)
    CollapsibleSchemas bool   // Deprecated: has no effect (v1.3.0+)
    CustomCSS          string // Raw CSS injected verbatim into the docs page (trusted input only)
    ScalarVersion      string // Pin @scalar/api-reference; "" = ui.DefaultScalarVersion ("1.75.0") (v1.3.0+)
    SpecCORSOrigin     string // Access-Control-Allow-Origin on the spec: "" = "*", "-" = omitted (v1.3.0+)
}

type DocsAuth struct {
    Enabled  bool   // Turn protection on
    Username string // Basic auth username
    Password string // Basic auth password
    Realm    string // Basic auth realm (optional)
    APIKey   string // Alternative: protect with an API key (?key=...)
}

type Info struct {
    Title          string   // API title
    Version        string   // Semantic version, e.g. "1.0.0"
    Description    string   // Markdown description
    TermsOfService string   // URL to terms of service
    Contact        *Contact // Maintainer contact info
    License        *License // License details
}

type Server struct {
    URL         string // Base URL, e.g. "https://api.example.com"
    Description string // Label for this server
}

type Tag struct {
    Name        string // Tag name referenced by Endpoint.Tags
    Description string // Displayed in the sidebar
}

type Contact struct {
    Name  string // Contact name
    URL   string // Contact URL
    Email string // Contact email
}

type License struct {
    Name string // License name, e.g. "MIT"
    URL  string // URL to the full license text
}

type ListProductsQuery struct {
    Page     int    `form:"page" description:"Page number" example:"1"`
    PerPage  int    `form:"per_page" description:"Items per page" example:"20"`
    Category string `form:"category" description:"Filter by category ID"`
}
 
type ProductPathParams struct {
    ID string `param:"id" description:"Product ID" example:"prod_123"`
}
 
openswag.Endpoint{
    Method:      "GET",
    Path:        "/products/{id}",
    PathParams:  ProductPathParams{},
    QueryParams: ListProductsQuery{},
    // ...
}

import "github.com/gopackx/open-swag-go/pkg/spec"
 
Parameters: []openswag.Parameter{
    {Name: "id", In: "path", Description: "User ID", Required: true, Schema: spec.NewSchema("string")},
},

package main
 
import (
    "log"
    "net/http"
    openswag "github.com/gopackx/open-swag-go"
)
 
func main() {
    cfg := openswag.Config{
        Info: openswag.Info{
            Title:   "Pet Store",
            Version: "1.0.0",
        },
        Servers: []openswag.Server{
            {URL: "http://localhost:8080", Description: "Local"},
        },
    }
 
    endpoints := []openswag.Endpoint{
        {
            Method:  "GET",
            Path:    "/pets",
            Summary: "List all pets",
            Tags:    []string{"Pets"},
            Responses: openswag.Responses{
                200: openswag.Response("A list of pets"),
            },
        },
    }
 
    docs := openswag.New(cfg)
 
    docs.AddAll(endpoints...)
    if err := docs.Validate(); err != nil {
        log.Fatal(err)
    }
    http.Handle("/docs/", docs.Handler())
    http.ListenAndServe(":8080", nil)
}