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

// 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)
}

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 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 WithHiddenClients(hiddenClients []string) func(*Options)
• func WithHideDownloadButton() func(*Options)
• func WithHideModels() func(*Options)
• func WithLayout(layout Layout) func(*Options)
• func WithMetaData(metaData string) 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 WithSidebarVisibility(visible bool) func(*Options)
• func WithSpecModifier(handler SpecModifier) func(*Options)
• func WithTheme(theme Theme) func(*Options)
• type Layout
• type Option
• type Options
• type SpecModifier
• type Theme

Constants

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

Functions

func New

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

New generates 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 sets the dark mode for the Scalar UI

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 WithHiddenClients

func WithHiddenClients(hiddenClients []string) func(*Options)

WithHiddenClients sets the hidden clients for the Scalar UI

func WithHideDownloadButton

func WithHideDownloadButton() func(*Options)

WithHideDownloadButton sets the download button visibility for the Scalar UI

func WithHideModels

func WithHideModels() func(*Options)

WithHideModels sets the models visibility for the Scalar UI

func WithLayout

func WithLayout(layout Layout) func(*Options)

WithLayout sets the layout for the Scalar UI

func WithMetaData

func WithMetaData(metaData string) func(*Options)

WithMetaData sets the metadata for the Scalar UI

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 WithSidebarVisibility

func WithSidebarVisibility(visible bool) func(*Options)

WithSidebarVisibility sets the sidebar visibility for the Scalar UI

func WithSpecModifier

func WithSpecModifier(handler SpecModifier) func(*Options)

WithSpecModifier allows to modify the spec before rendering

func WithTheme

func WithTheme(theme Theme) func(*Options)

WithTheme sets the theme for the Scalar UI

Types

type Layout

type Layout string

Layout represents different layout options

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

type Option

type Option func(*Options)

type Options

type Options struct {
	Theme              Theme        `json:"theme,omitempty"`
	Layout             Layout       `json:"layout,omitempty"`
	Proxy              string       `json:"proxy,omitempty"`
	IsEditable         bool         `json:"isEditable,omitempty"`
	ShowSidebar        bool         `json:"showSidebar,omitempty"`
	HideModels         bool         `json:"hideModels,omitempty"`
	HideDownloadButton bool         `json:"hideDownloadButton,omitempty"`
	DarkMode           bool         `json:"darkMode,omitempty"`
	SearchHotKey       string       `json:"searchHotKey,omitempty"`
	MetaData           string       `json:"metaData,omitempty"`
	HiddenClients      []string     `json:"hiddenClients,omitempty"`
	Authentication     string       `json:"authentication,omitempty"`
	PathRouting        string       `json:"pathRouting,omitempty"`
	BaseServerURL      string       `json:"baseServerUrl,omitempty"`
	WithDefaultFonts   bool         `json:"withDefaultFonts,omitempty"`
	OverrideCSS        string       `json:"-"`
	BaseFileName       string       `json:"-"`
	CDN                string       `json:"-"`
	OverrideHandler    SpecModifier `json:"-"`
}

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 = ""
)