apidoc

Documentation

Index

• Constants
• Variables
• func AddComponent(name string, v interface{})
• func DocList(w http.ResponseWriter, r *http.Request)
• func GetDoc(realPath, modName string) *openapi3.T
• func Markdown(w http.ResponseWriter, r *http.Request)
• func NilDoc()
• func OpenApi(mux *http.ServeMux, uriPrefix, dir string)
• func Redoc(opts RedocOpts, next http.Handler) http.Handler
• func Swagger(w http.ResponseWriter, r *http.Request)
• func WriteToFile(realPath, modName string)
• type ComponentType
• type RedocOpts
  • func (r *RedocOpts) EnsureDefaults()
• type UIOption
  • func WithTemplate(tpl string) UIOption
  • func WithUIBasePath(base string) UIOption
  • func WithUIPath(pth string) UIOption
  • func WithUISpecURL(specURL string) UIOption
  • func WithUITitle(title string) UIOption

Constants

const MarkDownEXT = ".apidoc.md"

const SwaggerEXT = ".swagger.json"

const TypeMarkdown = "markdown"

const TypeSwagger = "swagger"

Variables

var Dir = "./apidoc/"

var Doc *openapi3.T

var UriPrefix = "/apidoc"

目录结构 ./api/mod/mod.swagger.json ./api/mod/mod.apidoc.md 请求路由 /apidoc /apidoc/openapi/mod/mod.swagger.json /apidoc/markdown/mod/mod.apidoc.md

Functions

func AddComponent

func AddComponent(name string, v interface{})

func DocList

func DocList(w http.ResponseWriter, r *http.Request)

func GetDoc

func GetDoc(realPath, modName string) *openapi3.T

参数为路径和格式

func Markdown

func Markdown(w http.ResponseWriter, r *http.Request)

func NilDoc

func NilDoc()

func OpenApi

func OpenApi(mux *http.ServeMux, uriPrefix, dir string)

func Redoc

func Redoc(opts RedocOpts, next http.Handler) http.Handler

Redoc creates a middleware to serve a documentation site for a swagger spec.

This allows for altering the spec before starting the http listener.

func Swagger

func Swagger(w http.ResponseWriter, r *http.Request)

func WriteToFile

func WriteToFile(realPath, modName string)

Types

type ComponentType

type ComponentType int

const (
	ComponentTypeParameters ComponentType = iota
	ComponentTypeHeaders
	ComponentTypeRequestBodies
	ComponentTypeResponses
	ComponentTypeSecuritySchemes
	ComponentTypeExamples
	ComponentTypeLinks
	ComponentTypeCallbacks
)

type RedocOpts

type RedocOpts struct {
	// BasePath for the UI, defaults to: /
	BasePath string

	// Path combines with BasePath to construct the path to the UI, defaults to: "docs".
	Path string

	// SpecURL is the URL of the spec document.
	//
	// Defaults to: /swagger.json
	SpecURL string

	// Title for the documentation site, default to: API documentation
	Title string

	// Template specifies a custom template to serve the UI
	Template string

	// RedocURL points to the js that generates the redoc site.
	//
	// Defaults to: https://cdn.jsdelivr.net/npm/redoc/bundles/redoc.standalone.js
	RedocURL string
}

RedocOpts configures the Redoc middlewares

func (*RedocOpts) EnsureDefaults

func (r *RedocOpts) EnsureDefaults()

EnsureDefaults in case some options are missing

type UIOption

type UIOption func(*uiOptions)

UIOption can be applied to UI serving middleware, such as Context.APIHandler or Context.APIHandlerSwaggerUI to alter the defaut behavior.

func WithTemplate

func WithTemplate(tpl string) UIOption

WithTemplate allows to set a custom template for the UI.

UI middleware will panic if the template does not parse or execute properly.

func WithUIBasePath

func WithUIBasePath(base string) UIOption

WithUIBasePath sets the base path from where to serve the UI assets.

By default, Context middleware sets this value to the API base path.

func WithUIPath

func WithUIPath(pth string) UIOption

WithUIPath sets the path from where to serve the UI assets (i.e. /{basepath}/{path}.

func WithUISpecURL

func WithUISpecURL(specURL string) UIOption

WithUISpecURL sets the path from where to serve swagger spec document.

This may be specified as a full URL or a path.

By default, this is "/swagger.json"

func WithUITitle

func WithUITitle(title string) UIOption

WithUITitle sets the title of the UI.

By default, Context middleware sets this value to the title found in the API spec.