scalargo

README

Overview 🌐

The ScalarGo package serves as a provider for the Scalar project. It offers easy to integrate functions for documenting APIs in HTML format, with a focus on JSON data handling and web presentation customization. This includes functions to serialize options into JSON, manage HTML escaping, and dynamically handle different types of specification content.

Features 🚀

Supports reading API specification from a directory with multiple files, a single file.

Reading from single file

// When file is located in directory /example/docs/ and filename is api.yaml(default lookup name)
content, err := scalargo.New("/example/docs/")

// When file is located in directory /example/docs/ and filename is different from default lookup name e.g. petstore.yaml
content, err := scalargo.New(
    "/example/docs/",
    scalargo.WithBaseFileName("petstore.yaml"),
)

Reading from segmented files

The package supports reading segmented API specification files over schemas and paths. The segmented files are combined into a single specification file before generating the API reference.

Expected directory structure:

/example/docs/
    ├── api.yaml            // main file
    ├── schemas/            // directory for schema files
    │   ├── pet.yaml
    │   ├── user.yaml
    │   └── order.yaml
    ├── paths/              // directory for path files
    │   ├── pet.yaml
    │   ├── user.yaml
    │   └── order.yaml
    ├── responses/          // directory for response files
    └── └── Error.yaml

// When segmented files are located in directory /example/docs/ following the expected directory structure
content, err := scalargo.New("/example/docs/")

Customization Options ⚙️

The package allows extensive customization of the generated API reference through the Options

supporting scalar built-in options:

• Theme: Select theme for scalar UI from available themes.
• Layout: Chose between modern and classic layout designs
• ShowSidebar: Show or hide the sidebar in the API reference.
• HideModels: Hide the models section in the API reference.
• HideDownloadButton: Hide the download button in the API reference.
• DarkMode: Default dark mode for the API reference.
• SearchHotKey: Set a hotkey for the search functionality.
• MetaData: Set metadata for the API reference.
• HiddenClients: Hide clients in the API reference.

and customer options for easy of documenting APIs:

• OverrideCSS: A custom CSS style to override the default scalar style.
• BaseFileName: The base file name if it is not api.yml.
• CDN: URL of the CDN to load additional scripts or styles.

Usage 📚

package main

import (
    "net/http"

    scalargo "github.com/bdpiprava/scalar-go"
    "github.com/bdpiprava/scalar-go/model"
)

func main() {
    apiDir := "path/to/api/directory"
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        content, err := scalargo.New(
            apiDir,
            scalargo.WithBaseFileName("api.yml"),
            scalargo.WithSpecModifier(func(spec *model.Spec) *model.Spec { 
              // Customise the spec here
              spec.Info.Title = "PetStore API"
              return spec
            }),
        )

        if err != nil {
            http.Error(w, err.Error(), http.StatusInternalServerError)
            return
        }
        w.Write([]byte(content))
    })
    http.ListenAndServe(":8090", nil)
}

See the examples for more details.

Credits 🙏

• Scalar - The project that inspired this package.
• Go Scalar API Reference - The package that inspired this package.

Documentation

Index

• Constants
• func New(apiFilesDir string, opts ...Option) (string, error)
• func NewV2(opts ...Option) (string, error)
• func WithAuthentication(authentication string) func(*Options)
• func WithBaseFileName(baseFileName string) func(*Options)
• func WithBaseServerURL(baseServerURL string) func(*Options)
• func WithCDN(cdn string) func(*Options)
• func WithDarkMode() func(*Options)
• func WithDefaultFonts() func(*Options)
• func WithEditable() func(*Options)
• func WithForceDarkMode() func(*Options)
• func WithHiddenClients(hiddenClients ...string) func(*Options)
• func WithHideAllClients() func(*Options)
• func WithHideDarkModeToggle() func(*Options)
• func WithHideDownloadButton() func(*Options)
• func WithHideModels() func(*Options)
• func WithKeyValue(key string, value any) func(MetaData)
• func WithLayout(layout Layout) func(*Options)
• func WithMetaDataOpts(metadataOpts ...MetaOption) func(*Options)
• func WithOverrideCSS(overrideCSS string) func(*Options)
• func WithPathRouting(pathRouting string) func(*Options)
• func WithProxy(proxy string) func(*Options)
• func WithSearchHotKey(searchHotKey string) func(*Options)
• func WithServers(servers ...Server) func(*Options)
• func WithSidebarVisibility(visible bool) func(*Options)
• func WithSpecDir(specDir string) func(*Options)
• func WithSpecModifier(handler SpecModifier) func(*Options)
• func WithSpecURL(specURL string) func(*Options)
• func WithTheme(theme Theme) func(*Options)
• func WithTitle(title string) func(MetaData)
• type Layout
• type MetaData
• type MetaOption
• type Option
• type Options
  • func (o *Options) GetSpecScript() (string, error)
• type Server
• type SpecModifier
• type Theme

Constants

const DefaultCDN = "https://cdn.jsdelivr.net/npm/@scalar/api-reference"

DefaultCDN default CDN for api-reference

Functions

func New

func New(apiFilesDir string, opts ...Option) (string, error)

New generates the HTML for the Scalar UI

func NewV2

func NewV2(opts ...Option) (string, error)

NewV2 generate the HTML for the Scalar UI

func WithAuthentication

func WithAuthentication(authentication string) func(*Options)

WithAuthentication sets the authentication method for the Scalar UI

func WithBaseFileName

func WithBaseFileName(baseFileName string) func(*Options)

WithBaseFileName sets the base file name for the Scalar UI

func WithBaseServerURL

func WithBaseServerURL(baseServerURL string) func(*Options)

WithBaseServerURL sets the base server URL for the Scalar UI

func WithCDN

func WithCDN(cdn string) func(*Options)

WithCDN sets the CDN for the Scalar UI

func WithDarkMode

func WithDarkMode() func(*Options)

WithDarkMode set the dark mode as default

func WithDefaultFonts

func WithDefaultFonts() func(*Options)

WithDefaultFonts sets the default fonts usage for the Scalar UI

func WithEditable

func WithEditable() func(*Options)

WithEditable sets the editable state for the Scalar UI

func WithForceDarkMode

func WithForceDarkMode() func(*Options)

WithForceDarkMode makes it always this state no matter what

func WithHiddenClients

func WithHiddenClients(hiddenClients ...string) func(*Options)

WithHiddenClients hide the set clients

func WithHideAllClients

func WithHideAllClients() func(*Options)

WithHideAllClients sets the hidden clients for the Scalar UI

func WithHideDarkModeToggle

func WithHideDarkModeToggle() func(*Options)

WithHideDarkModeToggle hides the dark mode toggle button

func WithHideDownloadButton

func WithHideDownloadButton() func(*Options)

WithHideDownloadButton hide to download OpenAPI spec button

func WithHideModels

func WithHideModels() func(*Options)

WithHideModels sets the models visibility for the Scalar UI

func WithKeyValue

func WithKeyValue(key string, value any) func(MetaData)

WithKeyValue add metadata with key and value

func WithLayout

func WithLayout(layout Layout) func(*Options)

WithLayout sets the layout for the Scalar UI

func WithMetaDataOpts

func WithMetaDataOpts(metadataOpts ...MetaOption) func(*Options)

WithMetaDataOpts add metadata

func WithOverrideCSS

func WithOverrideCSS(overrideCSS string) func(*Options)

WithOverrideCSS sets the override CSS for the Scalar UI

func WithPathRouting

func WithPathRouting(pathRouting string) func(*Options)

WithPathRouting sets the path routing for the Scalar UI

func WithProxy

func WithProxy(proxy string) func(*Options)

WithProxy sets the proxy for the Scalar UI

func WithSearchHotKey

func WithSearchHotKey(searchHotKey string) func(*Options)

WithSearchHotKey sets the search hot key for the Scalar UI

func WithServers

func WithServers(servers ...Server) func(*Options)

WithServers servers to override the openapi spec servers

func WithSidebarVisibility

func WithSidebarVisibility(visible bool) func(*Options)

WithSidebarVisibility sets the sidebar visibility for the Scalar UI

func WithSpecDir

func WithSpecDir(specDir string) func(*Options)

WithSpecDir read spec from directory

func WithSpecModifier

func WithSpecModifier(handler SpecModifier) func(*Options)

WithSpecModifier allows to modify the spec before rendering

func WithSpecURL

func WithSpecURL(specURL string) func(*Options)

WithSpecURL set the spec URL in the doc

func WithTheme

func WithTheme(theme Theme) func(*Options)

WithTheme sets the theme for the Scalar UI

func WithTitle

func WithTitle(title string) func(MetaData)

WithTitle add title with value in metadata

Types

type Layout

type Layout string

Layout represents different layout options

const (
	LayoutModern  Layout = "modern"
	LayoutClassic Layout = "classic"
)

type MetaData

type MetaData map[string]any

MetaData metadata information for Scalar UI

type MetaOption

type MetaOption func(MetaData)

type Option

type Option func(*Options)

type Options

type Options struct {
	Configurations map[string]any
	OverrideCSS    string
	BaseFileName   string
	CDN            string
	SpecModifier   SpecModifier
	SpecDirectory  string
	SpecURL        string
}

func (*Options) GetSpecScript

func (o *Options) GetSpecScript() (string, error)

GetSpecScript prepare and return spec script

type Server

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

Server represtnts server override configuration

type SpecModifier

type SpecModifier func(spec *model.Spec) *model.Spec

SpecModifier is a function that can be used to override the spec

type Theme

type Theme string

Theme as a type based on string for theme identification

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