scalar

README

Scalar for Go

This package provides an easy way to render a beautiful API reference based on an OpenAPI/Swagger file with Scalar.

Installation

go get github.com/pakornv/scalar-go

Usage

See Scalar official documentation for more configuration details.

package main

import (
  "net/http"

  "github.com/pakornv/scalar-go"
)

func main() {
  apiRef, err := scalar.New("https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.yaml")
  if err != nil {
    panic(err)
  }

  router := http.NewServeMux()
  router.HandleFunc("GET /reference", func(w http.ResponseWriter, r *http.Request) {
    htmlContent, err := apiRef.RenderHTML()
    if err != nil {
      http.Error(w, err.Error(), http.StatusInternalServerError)
      return
    }

    w.Write([]byte(htmlContent))
  })

  http.ListenAndServe(":3000", router)
}

Credits

• Scalar
• Go Scalar API Reference

License

The source code in this repository is licensed under MIT.

Documentation

Index

• Constants
• type Config
• type ForceDarkModeState
• type HTTPClient
• type HTTPClientState
• type Layout
• type PathRouting
• type Scalar
  • func New(specURL string, cfg *Config) (*Scalar, error)
  • func (s *Scalar) RenderHTML() (string, error)
• type Server
• type Theme

Constants

const (
	DefaultTitle = "Scalar API Reference"
	DefaultCDN   = "https://cdn.jsdelivr.net/npm/@scalar/api-reference"
)

Types

type Config

type Config struct {

	// A string to use one of the color presets
	Theme Theme `json:"theme,omitempty"`

	// The layout to use for the references
	Layout Layout `json:"layout,omitempty"`

	// URL to a request proxy for the API client
	ProxyURL string `json:"proxyUrl,omitempty"`

	// Whether the spec input should show
	IsEditable *bool `json:"isEditable,omitempty"`

	// Whether to show the sidebar
	ShowSidebar *bool `json:"showSidebar,omitempty"`

	// Whether to show models in the sidebar, search, and content.
	// Default: false
	HideModels *bool `json:"hideModels,omitempty"`

	// Whether to show the "Download OpenAPI Document" button
	// Default: false
	HideDownloadButton *bool `json:"hideDownloadButton,omitempty"`

	// Whether to show the "Test Request" button
	// Default: false
	HideTestRequestButton *bool `json:"hideTestRequestButton,omitempty"`

	// Whether to show the sidebar search bar
	// Default: false
	HideSearch *bool `json:"hideSearch,omitempty"`

	// Whether dark mode is on or off initially (light mode)
	DarkMode *bool `json:"darkMode,omitempty"`

	// forceDarkModeState makes it always this state no matter what
	ForceDarkModeState ForceDarkModeState `json:"forceDarkModeState,omitempty"`

	// Whether to show the dark mode toggle
	HideDarkModeToggle *bool `json:"hideDarkModeToggle,omitempty"`

	// Key used with CTRL/CMD to open the search modal (defaults to 'k' e.g. CMD+k)
	SearchHotKey string `json:"searchHotKey,omitempty"` // one character from a-z

	// if used, passed data will be added to the HTML header
	// See: https://unhead.unjs.io/usage/composables/use-seo-meta
	MetaData map[string]string `json:"metaData,omitempty"`

	// Path to a favicon image
	// Default: undefined
	// Example: '/favicon.svg'
	Favicon string `json:"favicon,omitempty"`

	// List of httpsnippet clients to hide from the clients menu
	// By default hides Unirest, pass empty slice to show all clients
	HiddenClients []HTTPClient `json:"hiddenClients,omitempty"`

	// Determine the HTTP client that's selected by default
	DefaultHTTPClient *HTTPClientState `json:"defaultHttpClient,omitempty"`

	// Custom CSS to be added to the page
	CustomCSS string `json:"customCss,omitempty"`

	// Prefill authentication
	Authentication map[string]any `json:"authentication,omitempty"`

	// Route using paths instead of hashes, your server MUST support this
	// for example vue router needs a catch all so any subpaths are included
	//
	// Example:
	// '/standalone-api-reference/:custom(.*)?'
	//
	// Experimental
	// Default: undefined
	PathRouting *PathRouting `json:"pathRouting,omitempty"`

	// The baseServerURL is used when the spec servers are relative paths and we are using SSR
	// Default: undefined
	// Example: 'http://localhost:3000'
	BaseServerURL string `json:"baseServerURL,omitempty"`

	// List of servers to override the openapi spec servers
	Server []Server `json:"servers,omitempty"`

	// We're using Inter and JetBrains Mono as the default fonts. If you want to use your own fonts, set this to false.
	// Default: true
	WithDefaultFonts *bool `json:"withDefaultFonts,omitempty"`

	// By default we only open the relevant tag based on the url, however if you want all the tags open by default then set this configuration option
	// Default: false
	DefaultOpenAllTags *bool `json:"defaultOpenAllTags,omitempty"`

	// Whether to show the client button from the reference sidebar and modal
	// Default: false
	HideClientButton *bool `json:"hideClientButton,omitempty"`

	// Additional properties not in the official configuration
	Title string `json:"-"` // Title of the page
	CDN   string `json:"-"` // URL to the Scalar CDN
}

Config represents the configuration options for the reference For more information, see: https://github.com/scalar/scalar/blob/main/documentation/configuration.md

type ForceDarkModeState

type ForceDarkModeState string

const (
	Dark  ForceDarkModeState = "dark"
	Light ForceDarkModeState = "light"
)

type HTTPClient

type HTTPClient string

HTTPClient represents available clients

const (
	CLibcurl             HTTPClient = "c/libcurl"
	ClojureHTTP          HTTPClient = "clojure/clj_http"
	CSharpHTTPClient     HTTPClient = "csharp/httpclient"
	CSharpRestSharp      HTTPClient = "csharp/restsharp"
	GoNative             HTTPClient = "go/native"
	HTTPOnePOne          HTTPClient = "http/http1.1"
	JavaAsyncHTTP        HTTPClient = "java/asynchttp"
	JavaNetHTTP          HTTPClient = "java/nethttp"
	JavaOkHTTP           HTTPClient = "java/okhttp"
	JavaUnirest          HTTPClient = "java/unirest"
	JSAxios              HTTPClient = "js/axios"
	JSFetch              HTTPClient = "js/fetch"
	JSJQuery             HTTPClient = "js/jquery"
	JSOfetch             HTTPClient = "js/ofetch"
	JSXHR                HTTPClient = "js/xhr"
	KotlinOkHTTP         HTTPClient = "kotlin/okhttp"
	NodeAxios            HTTPClient = "node/axios"
	NodeFetch            HTTPClient = "node/fetch"
	NodeOfetch           HTTPClient = "node/ofetch"
	NodeUndici           HTTPClient = "node/undici"
	ObjcNSURLSession     HTTPClient = "objc/nsurlsession"
	OCamlCoHTTP          HTTPClient = "ocaml/cohttp"
	PHPCurl              HTTPClient = "php/curl"
	PHPGuzzle            HTTPClient = "php/guzzle"
	PowerShellRestmethod HTTPClient = "powershell/restmethod"
	PowerShellWebRequest HTTPClient = "powershell/webrequest"
	PythonPython3        HTTPClient = "python/python3"
	PythonRequests       HTTPClient = "python/requests"
	RHttr                HTTPClient = "r/httr"
	RubyNative           HTTPClient = "ruby/native"
	ShellCurl            HTTPClient = "shell/curl"
	ShellHTTPie          HTTPClient = "shell/httpie"
	ShellWGet            HTTPClient = "shell/wget"
	SwiftNSURLSession    HTTPClient = "swift/nsurlsession"
	DartHTTP             HTTPClient = "dart/http"
)

type HTTPClientState

type HTTPClientState struct {
	TargetKey string `json:"targetKey"`
	ClientKey string `json:"clientKey"`
}

type Layout

type Layout string

Layout represents available layouts

const LayoutClassic Layout = "classic"

const LayoutModern Layout = "modern"

type PathRouting

type PathRouting struct {
	BasePath string `json:"basePath"`
}

type Scalar

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

func New

func New(specURL string, cfg *Config) (*Scalar, error)

New creates a new instance of the Scalar API reference

func (*Scalar) RenderHTML

func (s *Scalar) RenderHTML() (string, error)

RenderHTML renders the HTML content for the API reference

type Server

type Server struct {
	URL         string `json:"url"`
	Description string `json:"description,omitempty"`
}

type Theme

type Theme string

Theme represents available themes

const (
	ThemeAlternate  Theme = "alternate"
	ThemeDefault    Theme = "default"
	ThemeMoon       Theme = "moon"
	ThemePurple     Theme = "purple"
	ThemeSolarized  Theme = "solarized"
	ThemeBluePlanet Theme = "bluePlanet"
	ThemeDeepSpace  Theme = "deepSpace"
	ThemeSaturn     Theme = "saturn"
	ThemeKepler     Theme = "kepler"
	ThemeElysiajs   Theme = "elysiajs"
	ThemeFastify    Theme = "fastify"
	ThemeMars       Theme = "mars"
	ThemeNone       Theme = "none"
)