boxopenapi

README

BoxOpenAPI

BoxOpenAPI leverages all the API information you have already defined with Box to generate your OpenAPI specification, including your types.

The function Spec returns an OpenAPI struct that can be easily serialized to JSON. However, if you prefer the YAML format, you can use the following code:

import (
	"bytes"
	"encoding/json"
	"strings"

	"github.com/itchyny/json2yaml"
)

// ToYaml converts a given object to its YAML representation.
func ToYaml(a any) string {
	var output strings.Builder
	b, _ := json.Marshal(a)
	json2yaml.Convert(&output, bytes.NewReader(b))
	return output.String()
}

Why is this function not included in the library?

The primary reason for not including this function in the library is to avoid introducing additional dependencies into your software supply chain, which can be difficult to justify.

Documentation

Index

• type Contact
• type Info
• type JSON
• type License
• type OpenAPI
  • func Spec(api *box.B) OpenAPI
• type Server
• type Variable

Types

type Contact

type Contact struct {
	Name  string `json:"name,omitempty"`
	Url   string `json:"url,omitempty"`
	Email string `json:"email,omitempty"`
}

Contact follows the spec from https://swagger.io/specification/#contact-object

type Info

type Info struct {
	Title          string   `json:"title"`
	Summary        string   `json:"summary,omitempty"`
	Description    string   `json:"description,omitempty"`
	TermsOfService string   `json:"termsOfService,omitempty"`
	Contact        *Contact `json:"contact,omitempty"`
	License        *License `json:"license,omitempty"`
	Version        string   `json:"version"`
}

Info follows the spec from https://swagger.io/specification/#info-object

type JSON

type JSON = map[string]any

type License

type License struct {
	Name       string `json:"name"`
	Identifier string `json:"identifier,omitempty"`
	Url        string `json:"url,omitempty"`
}

License follows the spec from https://swagger.io/specification/#license-object

type OpenAPI

type OpenAPI struct {
	Openapi           string   `json:"openapi"`
	Info              Info     `json:"info"`
	JsonSchemaDialect string   `json:"jsonSchemaDialect,omitempty"`
	Servers           []Server `json:"servers,omitempty"`
	Paths             JSON     `json:"paths,omitempty"`
	Webhooks          JSON     `json:"webhooks,omitempty"`
	Components        JSON     `json:"components,omitempty"`
	Security          []JSON   `json:"security,omitempty"`
	Tags              []JSON   `json:"tags,omitempty"`
	ExternalDocs      JSON     `json:"externalDocs,omitempty"`
}

OpenAPI follows the spec from https://swagger.io/specification/#openapi-object

func Spec

func Spec(api *box.B) OpenAPI

Spec returns a valid OpenAPI spec from a box router ready to be used.

type Server

type Server struct {
	Url         string              `json:"url"`
	Description string              `json:"description,omitempty"`
	Variables   map[string]Variable `json:"variables,omitempty"`
}

Server follows the spec from https://swagger.io/specification/#server-object

type Variable

type Variable struct {
	Enum        []string `json:"enum,omitempty"`
	Default     string   `json:"default"`
	Description string   `json:"description"`
}

Variable follows the spec from https://swagger.io/specification/#server-variable-object