scalargo

package module
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 26, 2024 License: MIT Imports: 5 Imported by: 2

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

Credits 🙏

Documentation

Index

Constants

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

DefaultCDN default CDN for api-reference

Variables

This section is empty.

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 WithForceDarkMode added in v0.5.0 

func WithForceDarkMode() func(*Options)

WithForceDarkMode makes it always this state no matter what

func WithHiddenClients 

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

WithHiddenClients sets the hidden clients for the Scalar UI

func WithHideDarkModeToggle added in v0.5.0 

func WithHideDarkModeToggle() func(*Options)

WithHideDarkModeToggle hides the dark mode toggle button

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 WithKeyValue added in v0.5.0 

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 added in v0.5.0 

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 added in v0.5.0 

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 WithSpecModifier added in v0.0.6 

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

func WithTitle added in v0.5.0 

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 added in v0.5.0 

type MetaData map[string]any

MetaData metadata information for Scalar UI

type MetaOption added in v0.5.0 

type MetaOption func(MetaData)

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"`
	FroceDarkMode      bool         `json:"forceDarkModeState,omitempty"`
	HideDarkModeToggle bool         `json:"hideDarkModeToggle,omitempty"`
	SearchHotKey       string       `json:"searchHotKey,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"`
	Servers            []Server     `json:"servers,omitempty"`
	MetaData           MetaData     `json:"metadata,omitempty"`
	OverrideCSS        string       `json:"-"`
	BaseFileName       string       `json:"-"`
	CDN                string       `json:"-"`
	OverrideHandler    SpecModifier `json:"-"`
}

type Server added in v0.5.0 

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

Server represtnts server override configuration

type SpecModifier added in v0.0.6 

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

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.