scalar

README

Overview 🌐

The Scalar package serves as a provider for the Scalar project. It offers a comprehensive suite of functions designed for generating API references in HTML format, specializing in 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 🚀

JSON Serialization and HTML Escaping

• safeJSONConfiguration 🔒: Serializes configuration options into JSON format and escapes HTML characters to prevent XSS attacks. This ensures that the JSON can be safely embedded within HTML documents.

Specification Content Handling

• specContentHandler 📝: Dynamically handles different types of specification content. It can process content as a function returning a map, a direct map, or a plain string, converting the specification content into JSON format suitable for web use.

HTML Generation

• ApiReferenceHTML 📄: Generates a complete HTML document for API reference. It allows for extensive customization, including themes, layouts, and CDN configuration. It handles both direct specification content and content fetched from a URL, providing error handling for missing specifications.

Customization Options ⚙️

The package allows extensive customization of the generated API reference through the Options struct, supporting:

• CDN: URL of the CDN to load additional scripts or styles.
• Theme: Customizable themes for styling the API reference.
• Layout: Choice between modern and classic layout designs.
• SpecURL: URL from which the specification content can be fetched.
• Dark Mode: Option to enable a dark theme for the API reference.

Themes and Styles 🎨

• Provides a default set of CSS styles for both light and dark themes.
• Allows custom CSS injections to tailor the appearance to specific branding or aesthetic requirements.

Error Handling 🛠️

• Robust error handling for scenarios where necessary parameters like SpecURL or SpecContent are missing.
• Errors during the fetching of specification content from URLs are properly managed and reported.

Usage 📚

To use the Scalar package as a provider in your Go project for creating API references, follow the example below:

package main

import (
	"fmt"
	"net/http"

	"github.com/go-chi/chi/v5"
	"github.com/go-chi/chi/v5/middleware"

	"github.com/MarceloPetrucio/go-scalar-api-reference"
)

func main() {
	router := chi.NewRouter()

	router.Use(middleware.RequestID)
	router.Use(middleware.Logger)
	router.Use(middleware.Recoverer)

	router.Get("/", create)

	router.Get("/reference", func(w http.ResponseWriter, r *http.Request) {
		htmlContent, err := scalar.ApiReferenceHTML(&scalar.Options{
			// SpecURL: "https://generator3.swagger.io/openapi.json",// allow external URL or local path file
			SpecURL: "./docs/swagger.json", 
			CustomOptions: scalar.CustomOptions{
				PageTitle: "Simple API",
			},
			DarkMode: true,
		})

		if err != nil {
			fmt.Printf("%v", err)
		}

		fmt.Fprintln(w, htmlContent)
	})

	fmt.Printf("Starting web server on port :8000")
	http.ListenAndServe(":8000", router)
}

Documentation

Index

• Constants
• func ApiReferenceHTML(optionsInput *Options) (string, error)
• type CustomOptions
• type Options
  • func DefaultOptions(option Options) *Options
• type ReferenceLayoutType
• type ThemeId

Constants

const CustomThemeCSS = `` /* 2343-byte string literal not displayed */

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

Functions

func ApiReferenceHTML

func ApiReferenceHTML(optionsInput *Options) (string, error)

Types

type CustomOptions

type CustomOptions struct {
	PageTitle string `json:"pageTitle,omitempty"`
}

type Options

type Options struct {
	CDN                string              `json:"cdn,omitempty"`
	Theme              ThemeId             `json:"theme,omitempty"`
	Layout             ReferenceLayoutType `json:"layout,omitempty"`
	SpecURL            string              `json:"specUrl,omitempty"` // allow external URL ou local path file
	SpecContent        interface{}         `json:"specContent,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"`
	CustomCss          string              `json:"customCss,omitempty"`
	Authentication     string              `json:"authentication,omitempty"`
	PathRouting        string              `json:"pathRouting,omitempty"`
	BaseServerURL      string              `json:"baseServerUrl,omitempty"`
	WithDefaultFonts   bool                `json:"withDefaultFonts,omitempty"`
	CustomOptions
}

func DefaultOptions

func DefaultOptions(option Options) *Options

DefaultOptions configures the default settings for API Reference options

type ReferenceLayoutType

type ReferenceLayoutType string

ReferenceLayoutType represents different layout options

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

type ThemeId

type ThemeId string

Define ThemeId as a type based on string for theme identification

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