swagger

README

Rig Swagger

Swagger UI support for Rig.

This is a separate sub-package to keep the core Rig framework dependency-free.

Installation

go get github.com/cloudresty/rig/swagger

Usage

With swaggo/swag (Recommended)

Generate your API spec using swaggo/swag:

swag init

Then integrate with Rig:

package main

import (
    "github.com/cloudresty/rig"
    "github.com/cloudresty/rig/swagger"
    _ "myapp/docs" // Generated by swag init
)

func main() {
    r := rig.New()

    // Your API routes
    r.GET("/api/v1/users", handleUsers)

    // Register Swagger UI
    sw := swagger.NewFromSwag("swagger")
    sw.Register(r, "/docs")

    r.Run(":8080")
}

With Custom Spec

spec := `{"openapi":"3.0.0","info":{"title":"My API","version":"1.0"}}`
sw := swagger.New(spec).
    WithTitle("My API Documentation").
    WithDocExpansion("list")
sw.Register(r, "/api-docs")

With Route Groups

api := r.Group("/api/v1")
sw := swagger.NewFromSwag("swagger")
sw.RegisterGroup(api, "/docs")
// Access at /api/v1/docs/

API

Method	Description
New(specJSON)	Create with JSON spec string
NewFromSwag(name)	Create from swaggo/swag registered spec
WithTitle(title)	Set page title
WithDeepLinking(bool)	Enable/disable URL deep linking
WithDocExpansion(mode)	Set expansion: "list", "full", "none"
Register(router, path)	Register on Router
RegisterGroup(group, path)	Register on RouteGroup

License

MIT License - see LICENSE

Documentation

Overview

Package swagger provides Swagger UI support for Rig. This is a separate package to keep the core Rig framework dependency-free.

Index

• type Swagger
  • func New(specJSON string) *Swagger
  • func NewFromSwag(instanceName string) *Swagger
  • func (s *Swagger) Register(r *rig.Router, pathPrefix string)
  • func (s *Swagger) RegisterGroup(g *rig.RouteGroup, pathPrefix string)
  • func (s *Swagger) WithDeepLinking(enabled bool) *Swagger
  • func (s *Swagger) WithDocExpansion(mode string) *Swagger
  • func (s *Swagger) WithTitle(title string) *Swagger

Types

type Swagger

type Swagger struct {
	// contains filtered or unexported fields
}

Swagger provides Swagger UI serving capabilities.

func New

func New(specJSON string) *Swagger

New creates a new Swagger UI server with the given OpenAPI/Swagger spec JSON.

func NewFromSwag

func NewFromSwag(instanceName string) *Swagger

NewFromSwag creates a Swagger UI server using swaggo/swag's registered spec. The instanceName is typically "swagger" unless you registered a custom name. Requires importing your generated docs package: _ "myapp/docs"

func (*Swagger) Register

func (s *Swagger) Register(r *rig.Router, pathPrefix string)

Register registers Swagger UI routes at the given path prefix. Example: s.Register(router, "/docs") serves UI at /docs/

func (*Swagger) RegisterGroup

func (s *Swagger) RegisterGroup(g *rig.RouteGroup, pathPrefix string)

RegisterGroup registers Swagger UI routes on a route group. Example: s.RegisterGroup(apiGroup, "/docs") serves UI at /api/docs/

func (*Swagger) WithDeepLinking

func (s *Swagger) WithDeepLinking(enabled bool) *Swagger

WithDeepLinking enables or disables deep linking in Swagger UI. When enabled, the URL updates as you navigate the documentation. Default: true

func (*Swagger) WithDocExpansion

func (s *Swagger) WithDocExpansion(mode string) *Swagger

WithDocExpansion sets the default expansion mode for operations. Valid values: "list" (default), "full", "none"

func (*Swagger) WithTitle

func (s *Swagger) WithTitle(title string) *Swagger

WithTitle sets the page title for the Swagger UI.