chioas

README

CHIOAS

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

• Variables
• type Additional
• type Components
• type Contact
• type Definition
  • func (d *Definition) AsYaml() ([]byte, error)
  • func (d *Definition) SetupRoutes(router chi.Router, thisApi any) error
  • func (d *Definition) WriteYaml(w io.Writer) error
• type DocOptions
• type ExternalDocs
• type Info
• type License
• type Method
• type Methods
• type Path
• type PathParam
• type PathParams
• type Paths
• type Property
• type QueryParam
• type QueryParams
• type Request
• type Response
• type Responses
• type Schema
• type Schemas
• type Server
• type Servers
• type Tag
• type Tags

Variables

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

var OasVersion = "3.0.3"

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
	//Context     string
	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.htm")
	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)
	RedocOptions map[string]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
}

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
}

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
}

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