chioas

package module
v1.1.1 Latest Latest
Warning

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

 Go to latest Published: Jul 23, 2023 License: Apache-2.0 Imports: 15 Imported by: 0

README

CHIOAS

GoDoc Latest Version Go Report Card

Chioas is an add-on for the popular Chi router

pronounce Chioas however you like...

but I can't help feeling that it looks a little like "chaos" - the chaos of undocumented APIs that it tries to solve!

What it does

Chioas does three things:

  • Defines your API as a single (or modular) struct and then builds the Chi routes accordingly
  • Produces an OpenApi spec (OAS) of that definition
  • Optionally serves an interactive API docs web-page (as part of your service)
Basic Example
package main

import (
    "github.com/go-andiamo/chioas"
    "github.com/go-chi/chi/v5"
    "net/http"
)

func main() {
    router := chi.NewRouter()
    if err := myApi.SetupRoutes(router, myApi); err != nil {
        panic(err)
    }
    _ = http.ListenAndServe(":8080", router)
}

var myApi = chioas.Definition{
    DocOptions: chioas.DocOptions{
        ServeDocs: true,
    },
    Paths: map[string]chioas.Path{
        "/foos": {
            Methods: map[string]chioas.Method{
                http.MethodGet: {
                    Handler: getFoos,
                },
                http.MethodPost: {
                    Handler: postFoos,
                },
            },
            Paths: map[string]chioas.Path{
                "/{fooId}": {
                    Methods: map[string]chioas.Method{
                        http.MethodGet: {
                            Handler: getFoo,
                        },
                        http.MethodDelete: {
                            Handler: deleteFoo,
                        },
                    },
                },
            },
        },
    },
}

func getFoos(writer http.ResponseWriter, request *http.Request) {
}

func postFoos(writer http.ResponseWriter, request *http.Request) {
}

func getFoo(writer http.ResponseWriter, request *http.Request) {
}

func deleteFoo(writer http.ResponseWriter, request *http.Request) {
}

Run and then check out http://localhost:8080/docs !

Documentation

Overview

Package chioas - Go package for building OAS (OpenApi Specs) for Chi APIs

Index

Constants

This section is empty.

Variables

View Source 
var MethodsOrder = []string{
	http.MethodGet,
	http.MethodHead,
	http.MethodOptions,
	http.MethodPost,
	http.MethodPut,
	http.MethodPatch,
	http.MethodDelete,
}

MethodsOrder defines the order in which methods appear in docs

View Source 
var OasVersion = "3.0.3"

Functions

This section is empty.

Types

type Additional 

type Additional interface {
	Write(on any, w yaml.Writer)
}

Additional is an interface that can be supplied to many parts of the definition to write additional yaml to the OAS

type Components 

type Components struct {
	Schemas    Schemas
	Additional Additional
}

type Contact 

type Contact struct {
	Name  string
	Url   string
	Email string
}

type Definition 

type Definition struct {
	DocOptions      DocOptions
	AutoHeadMethods bool // set to true to automatically add HEAD methods for GET methods (and where HEAD method not explicitly specified)
	Info            Info
	Servers         Servers
	Tags            Tags
	Methods         Methods         // methods on api root
	Middlewares     chi.Middlewares // chi middlewares for api root
	Paths           Paths           // descendant paths
	Components      *Components
	Additional      Additional
}

Definition is the overall definition of an api

func (*Definition) AsYaml 

func (d *Definition) AsYaml() ([]byte, error)

func (*Definition) SetupRoutes 

func (d *Definition) SetupRoutes(router chi.Router, thisApi any) error

SetupRoutes sets up the API routes on the supplied chi.Router

Pass the thisApi arg if any of the methods use method by name

func (*Definition) WriteYaml 

func (d *Definition) WriteYaml(w io.Writer) error

type DocOptions 

type DocOptions struct {
	// ServeDocs whether to serve api docs
	ServeDocs bool
	// Context is the optional path prefix for all paths in OAS spec
	Context string
	// NoCache if set to true, docs page and spec aren't cached (and built on each call)
	NoCache bool
	// Path the path on which to serve api docs page and spec (defaults to "/docs")
	Path string
	// DocIndexPage the name of the docs index page (defaults to "index.html")
	DocIndexPage string
	// Title the title in the docs index page (defaults to "API Documentation")
	Title string
	// RedocOptions redoc options to be used (see https://github.com/Redocly/redoc#redoc-options-object)
	//
	// use map[string]any or &RedocOptions (or anything that can be marshalled and then unmarshalled to map[string]any)
	RedocOptions any
	// SpecName the name of the OAS spec (defaults to "spec.yaml")
	SpecName string
	// DocTemplate template for the docs page (defaults to internal template if an empty string)
	DocTemplate string
	// StylesOverride css styling overrides (injected into docs index page)
	StylesOverride string
	// DefaultResponses is the default responses for methods that don't have any responses defined
	//
	// is a map of http status code and response
	DefaultResponses Responses
	// HideHeadMethods indicates that all HEAD methods should be hidden from docs
	HideHeadMethods bool
}

DocOptions determines whether/how the api will serve interactive docs page

type ExternalDocs 

type ExternalDocs struct {
	Description string
	Url         string
}

type Info 

type Info struct {
	Title          string
	Description    string
	Version        string
	TermsOfService string
	Contact        *Contact
	License        *License
	Additional     Additional
	ExternalDocs   *ExternalDocs
}

type License 

type License struct {
	Name string
	Url  string
}

type Method 

type Method struct {
	Description string
	Summary     string
	Handler     any // can be a http.HandlerFunc or a string method name
	OperationId string
	Tag         string
	QueryParams QueryParams
	Request     *Request
	Responses   Responses
	Additional  Additional
	HideDocs    bool // hides this method from docs
}

type Methods 

type Methods map[string]Method

type Path 

type Path struct {
	Methods     Methods
	Paths       Paths
	Middlewares chi.Middlewares // chi middlewares for path
	Tag         string
	PathParams  PathParams
	HideDocs    bool // hides this path (and descendants) from docs
}

type PathParam 

type PathParam struct {
	Description string
	Example     any
	Additional  Additional
}

type PathParams 

type PathParams map[string]PathParam

type Paths 

type Paths map[string]Path

type Property 

type Property struct {
	Name        string
	Description string
	Type        string
	ItemType    string // only used if Type = "array"
	Example     any
	SchemaRef   string
	Additional  Additional
}

type QueryParam 

type QueryParam struct {
	Name        string
	Description string
	Required    bool
	Example     any
	Schema      *Schema
	SchemaRef   string
	Additional  Additional
}

type QueryParams 

type QueryParams []QueryParam

type RedocArrow added in v1.1.1 

type RedocArrow struct {
	Size  string `json:"size,omitempty"` // '1.5em'
	Color string `json:"color"`          // COMPUTED: theme.sidebar.textColor
}

type RedocBreakpoints added in v1.1.1 

type RedocBreakpoints struct {
	Small  string `json:"small,omitempty"`  // '50rem'
	Medium string `json:"medium,omitempty"` // '85rem'
	Large  string `json:"large"`            // '105rem'
}

RedocBreakpoints breakpoints for switching three/two and mobile view layouts

type RedocCode added in v1.1.1 

type RedocCode struct {
	FontSize        string `json:"fontSize,omitempty"`        // '13px'
	FontFamily      string `json:"fontFamily,omitempty"`      // 'Courier, monospace'
	LineHeight      string `json:"lineHeight,omitempty"`      // COMPUTED: typography.lineHeight
	FontWeight      string `json:"fontWeight,omitempty"`      // COMPUTED: typography.fontWeightRegular
	Color           string `json:"color,omitempty"`           // '#e53935'
	BackgroundColor string `json:"backgroundColor,omitempty"` // 'rgba(38, 50, 56, 0.05)'
	Wrap            bool   `json:"wrap,omitempty"`            // whether to break word for inline blocks (otherwise they can overflow)
}

type RedocColors added in v1.1.1 

type RedocColors struct {
	TonalOffset float32 `json:"tonalOffset,omitempty"` // 0.3 # default tonal offset used in computations
}

type RedocFab added in v1.1.1 

type RedocFab struct {
	BackgroundColor string `json:"backgroundColor,omitempty"` // '#263238'
	Color           string `json:"color,omitempty"`           // '#ffffff'
}

type RedocGroupItems added in v1.1.1 

type RedocGroupItems struct {
	ActiveBackgroundColor string `json:"activeBackgroundColor,omitempty"` // COMPUTED: theme.sidebar.backgroundColor
	ActiveTextColor       string `json:"activeTextColor"`                 // COMPUTED: theme.sidebar.activeTextColor
	TextTransform         string `json:"textTransform"`                   // 'uppercase'
}

type RedocHeadings added in v1.1.1 

type RedocHeadings struct {
	FontFamily string `json:"fontFamily,omitempty"` // 'Montserrat, sans-serif'
	FontWeight string `json:"fontWeight,omitempty"` // '400'
	LineHeight string `json:"lineHeight,omitempty"` // '1.6em'
}

type RedocLevel1Items added in v1.1.1 

type RedocLevel1Items struct {
	ActiveBackgroundColor string `json:"activeBackgroundColor,omitempty"` // COMPUTED: theme.sidebar.backgroundColor
	ActiveTextColor       string `json:"activeTextColor,omitempty"`       // COMPUTED: theme.sidebar.activeTextColor
	TextTransform         string `json:"textTransform"`                   // 'none'
}
type RedocLinks struct {
	Color               string `json:"color,omitempty"`          // COMPUTED: colors.primary.main
	Visited             string `json:"visited,omitempty"`        // COMPUTED: typography.links.color
	Hover               string `json:"hover,omitempty"`          // COMPUTED: lighten(0.2 typography.links.color)
	TextDecoration      string `json:"textDecoration,omitempty"` // 'auto'
	HoverTextDecoration string `json:"hoverTextDecoration"`      // 'auto'
}
type RedocLogo struct {
	MaxHeight int    `json:"maxHeight,omitempty"` // COMPUTED: sidebar.width
	MaxWidth  int    `json:"maxWidth,omitempty"`  // COMPUTED: sidebar.width
	Gutter    string `json:"gutter"`              // '2px' # logo image padding
}

type RedocOptions added in v1.1.1 

type RedocOptions struct {
	DisableSearch                   bool        `json:"disableSearch,omitempty"`                   // disable search indexing and search box.
	MinCharacterLengthToInitSearch  int         `json:"minCharacterLengthToInitSearch,omitempty"`  // set minimal characters length to init search, default 3, minimal 1.
	ExpandDefaultServerVariables    bool        `json:"expandDefaultServerVariables,omitempty"`    // enable expanding default server variables, default false.
	ExpandResponses                 string      `json:"expandResponses,omitempty"`                 // specify which responses to expand by default by response codes. Values should be passed as comma-separated list without spaces e.g. expandResponses="200,201". Special value "all" expands all responses by default. Be careful: this option can slow-down documentation rendering time.
	GeneratedPayloadSamplesMaxDepth int         `json:"generatedPayloadSamplesMaxDepth,omitempty"` // set the maximum render depth for JSON payload samples (responses and request body). The default value is 10.
	MaxDisplayedEnumValues          int         `json:"maxDisplayedEnumValues,omitempty"`          // display only specified number of enum values. hide rest values under spoiler.
	HideDownloadButton              bool        `json:"hideDownloadButton,omitempty"`              // do not show "Download" spec button. THIS DOESN'T MAKE YOUR SPEC PRIVATE, it just hides the button.
	DownloadFileName                string      `json:"downloadFileName,omitempty"`                // set a custom file name for the downloaded API definition file.
	DownloadDefinitionUrl           string      `json:"downloadDefinitionUrl,omitempty"`           // If the 'Download' button is visible in the API reference documentation (hideDownloadButton=false), the URL configured here opens when that button is selected. Provide it as an absolute URL with the full URI scheme.
	HideHostname                    bool        `json:"hideHostname,omitempty"`                    // if set, the protocol and hostname is not shown in the operation definition.
	HideLoading                     bool        `json:"hideLoading,omitempty"`                     // do not show loading animation. Useful for small docs.
	HideFab                         bool        `json:"hideFab,omitempty"`                         // do not show FAB in mobile view. Useful for implementing a custom floating action button.
	HideSchemaPattern               bool        `json:"hideSchemaPattern,omitempty"`               // if set, the pattern is not shown in the schema.
	HideSingleRequestSampleTab      bool        `json:"hideSingleRequestSampleTab,omitempty"`      // do not show the request sample tab for requests with only one sample.
	ShowObjectSchemaExamples        bool        `json:"showObjectSchemaExamples,omitempty"`        // show object schema example in the properties, default false.
	ExpandSingleSchemaField         bool        `json:"expandSingleSchemaField,omitempty"`         // automatically expand single field in a schema
	SchemaExpansionLevel            any         `json:"schemaExpansionLevel,omitempty"`            // specifies whether to automatically expand schemas. Special value "all" expands all levels. The default value is 0.
	JsonSampleExpandLevel           any         `json:"jsonSampleExpandLevel,omitempty"`           // set the default expand level for JSON payload samples (responses and request body). Special value "all" expands all levels. The default value is 2.
	HideSchemaTitles                bool        `json:"hideSchemaTitles,omitempty"`                // do not display schema title next to the type
	SimpleOneOfTypeLabel            bool        `json:"simpleOneOfTypeLabel,omitempty"`            // show only unique oneOf types in the label without titles
	SortEnumValuesAlphabetically    bool        `json:"sortEnumValuesAlphabetically,omitempty"`    // set to true, sorts all enum values in all schemas alphabetically
	SortOperationsAlphabetically    bool        `json:"sortOperationsAlphabetically,omitempty"`    // set to true, sorts operations in the navigation sidebar and in the middle panel alphabetically
	SortTagsAlphabetically          bool        `json:"sortTagsAlphabetically,omitempty"`          // set to true, sorts tags in the navigation sidebar and in the middle panel alphabetically
	MenuToggle                      bool        `json:"menuToggle,omitempty"`                      // if true, clicking second time on expanded menu item collapses it, default true.
	NativeScrollbars                bool        `json:"nativeScrollbars,omitempty"`                // use native scrollbar for sidemenu instead of perfect-scroll (scrolling performance optimization for big specs).
	OnlyRequiredInSamples           bool        `json:"onlyRequiredInSamples,omitempty"`           // shows only required fields in request samples.
	PathInMiddlePanel               bool        `json:"pathInMiddlePanel,omitempty"`               // show path link and HTTP verb in the middle panel instead of the right one.
	RequiredPropsFirst              bool        `json:"requiredPropsFirst,omitempty"`              // show required properties first ordered in the same order as in required array.
	ScrollYOffset                   any         `json:"scrollYOffset,omitempty"`                   // If set, specifies a vertical scroll-offset. This is often useful when there are fixed positioned elements at the top of the page, such as navbars, headers etc; scrollYOffset can be specified in various ways:
	ShowExtensions                  bool        `json:"showExtensions,omitempty"`                  // show vendor extensions ("x-" fields). Extensions used by Redoc are ignored. Can be boolean or an array of string with names of extensions to display.
	SortPropsAlphabetically         bool        `json:"sortPropsAlphabetically,omitempty"`         // sort properties alphabetically.
	PayloadSampleIndex              int         `json:"payloadSampleIdx,omitempty"`                // if set, payload sample is inserted at this index or last. Indexes start from 0.
	Theme                           *RedocTheme `json:"theme,omitempty"`                           // Redoc theme
	UntrustedSpec                   bool        `json:"untrustedSpec,omitempty"`                   // if set, the spec is considered untrusted and all HTML/markdown is sanitized to prevent XSS. Disabled by default for performance reasons. Enable this option if you work with untrusted user data!
	Nonce                           any         `json:"nonce,omitempty"`                           // if set, the provided value is injected in every injected HTML element in the nonce attribute. Useful when using CSP, see https://webpack.js.org/guides/csp/.
	SideNavStyle                    string      `json:"sideNavStyle,omitempty"`                    // can be specified in various ways: "summary-only" (default), "path-only" or id-only"
	ShowWebhookVerb                 bool        `json:"showWebhookVerb,omitempty"`                 // when set to true, shows the HTTP request method for webhooks in operations and in the sidebar.
}

RedocOptions for use in DocOptions.RedocOptions (from https://github.com/Redocly/redoc#redoc-options-object)

type RedocRightPanel added in v1.1.1 

type RedocRightPanel struct {
}

type RedocSidebar added in v1.1.1 

type RedocSidebar struct {
	Width           string            `json:"width,omitempty"`           // '260px'
	BackgroundColor string            `json:"backgroundColor,omitempty"` // '#fafafa'
	TextColor       string            `json:"textColor,omitempty"`       // '#333333'
	ActiveTextColor string            `json:"activeTextColor"`           // COMPUTED: theme.sidebar.textColor (if set by user) or theme.colors.primary.main
	GroupItems      *RedocGroupItems  `json:"groupItems,omitempty"`      // Group headings
	Level1Items     *RedocLevel1Items `json:"level1Items,omitempty"`     //  Level 1 items like tags or section 1st level items
	Arrow           *RedocArrow       `json:"arrow,omitempty"`           // sidebar arrow
}

type RedocSpacing added in v1.1.1 

type RedocSpacing struct {
	Unit              int `json:"unit,omitempty"`              // 5 # main spacing unit used in autocomputed theme values later
	SectionHorizontal int `json:"sectionHorizontal,omitempty"` // 40 # Horizontal section padding. COMPUTED: spacing.unit * 8
	SectionVertical   int `json:"sectionVertical,omitempty"`   // 40 # Horizontal section padding. COMPUTED: spacing.unit * 8
}

type RedocTheme added in v1.1.1 

type RedocTheme struct {
	Spacing     *RedocSpacing     `json:"spacing,omitempty"`
	Breakpoints *RedocBreakpoints `json:"breakpoints,omitempty"`
	Colors      *RedocColors      `json:"colors,omitempty"`
	Typography  *RedocTypography  `json:"typography,omitempty"`
	Sidebar     *RedocSidebar     `json:"sidebar,omitempty"`
	RightPanel  *RedocRightPanel  `json:"rightPanel,omitempty"`
	Fab         *RedocFab         `json:"fab,omitempty"`
}

type RedocTypography added in v1.1.1 

type RedocTypography struct {
	FontSize          string         `json:"fontSize,omitempty"`          // '14px'
	LineHeight        string         `json:"lineHeight,omitempty"`        // '1.5em'
	FontWeightRegular string         `json:"fontWeightRegular,omitempty"` // '400'
	FontWeightBold    string         `json:"fontWeightBold,omitempty"`    // '600'
	FontWeightLight   string         `json:"fontWeightLight,omitempty"`   // '300'
	FontFamily        string         `json:"fontFamily,omitempty"`        // 'Roboto, sans-serif'
	Smoothing         string         `json:"smoothing,omitempty"`         // 'antialiased'
	OptimizeSpeed     bool           `json:"optimizeSpeed"`               // true
	Headings          *RedocHeadings `json:"headings,omitempty"`
	Code              *RedocCode     `json:"code,omitempty"`
	Links             *RedocLinks    `json:"links,omitempty"`
}

type Request 

type Request struct {
	Description string
	Required    bool
	ContentType string // defaults to "application/json"
	Schema      any
	SchemaRef   string
	IsArray     bool // indicates that Schema or SchemaRef is an array of items
	Additional  Additional
}

type Response 

type Response struct {
	Description string
	ContentType string // defaults to "application/json"
	Schema      any
	SchemaRef   string
	IsArray     bool // indicates that Schema or SchemaRef is an array of items
	Additional  Additional
}

type Responses 

type Responses map[int]Response

type Schema 

type Schema struct {
	Name               string
	Description        string
	Type               string
	RequiredProperties []string
	Properties         []Property
	Default            any
	Enum               []any
	Additional         Additional
}

type Schemas 

type Schemas []Schema

type Server 

type Server struct {
	Description string
	Additional  Additional
}

type Servers 

type Servers map[string]Server

type Tag 

type Tag struct {
	Name         string
	Description  string
	ExternalDocs *ExternalDocs
	Additional   Additional
}

type Tags 

type Tags []Tag

Source Files

View all Source files

Directories

Path Synopsis
examples
basic
petstore

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.