docs

Documentation

Index

• Constants
• func DefaultStatus(type_ reflect.Type, default_ ...int) int
• type Docs
  • func New(options *Options) *Docs
  • func (d *Docs) NormalizePath(path string) string
  • func (d *Docs) PathItem(path string) *openapi3.PathItem
  • func (d *Docs) RegisterRoutes(router gin.IRouter)
  • func (d *Docs) SaveAsJson(path string) error
  • func (d *Docs) SaveAsYaml(path string) error
  • func (d *Docs) SetPath(path string, method string, doc *Endpoint)
• type Endpoint
  • func (e *Endpoint) AddErrorResponse(responseType reflect.Type)
  • func (e *Endpoint) AddHeadersType(headerType reflect.Type)
  • func (e *Endpoint) AddPathParam(name string, type_ reflect.Type)
  • func (e *Endpoint) AddResponse(responseType reflect.Type)
  • func (e *Endpoint) SetBodyType(bodyType reflect.Type)
  • func (e *Endpoint) SetQueryType(queryType reflect.Type)
  • func (e *Endpoint) SetTagsFromPath(path string)
• type Handler
  • func NewHandler(docs *Docs) *Handler
  • func (h *Handler) Docs(ctx *gin.Context)
  • func (h *Handler) JsonFile(ctx *gin.Context)
  • func (h *Handler) YamlFile(ctx *gin.Context)
• type Options

Constants

const (
	// NoUrl is used to recognize whether the url should be cleared/ignored or initialized with the default value.
	// If one of the urls in Options won't be filled, the default value will be used for it.
	// If you need to disable some url, use NoUrl.
	NoUrl = "-"
)

Functions

func DefaultStatus

func DefaultStatus(type_ reflect.Type, default_ ...int) int

Types

type Docs

type Docs struct {
	OpenApi        *openapi3.T
	InteractiveUrl string
	JsonUrl        string
	YamlUrl        string
}

func New

func New(options *Options) *Docs

func (*Docs) NormalizePath

func (d *Docs) NormalizePath(path string) string

func (*Docs) PathItem

func (d *Docs) PathItem(path string) *openapi3.PathItem

func (*Docs) RegisterRoutes

func (d *Docs) RegisterRoutes(router gin.IRouter)

func (*Docs) SaveAsJson

func (d *Docs) SaveAsJson(path string) error

func (*Docs) SaveAsYaml

func (d *Docs) SaveAsYaml(path string) error

func (*Docs) SetPath

func (d *Docs) SetPath(path string, method string, doc *Endpoint)

type Endpoint

type Endpoint openapi3.Operation

func (*Endpoint) AddErrorResponse

func (e *Endpoint) AddErrorResponse(responseType reflect.Type)

func (*Endpoint) AddHeadersType

func (e *Endpoint) AddHeadersType(headerType reflect.Type)

func (*Endpoint) AddPathParam

func (e *Endpoint) AddPathParam(name string, type_ reflect.Type)

func (*Endpoint) AddResponse

func (e *Endpoint) AddResponse(responseType reflect.Type)

func (*Endpoint) SetBodyType

func (e *Endpoint) SetBodyType(bodyType reflect.Type)

func (*Endpoint) SetQueryType

func (e *Endpoint) SetQueryType(queryType reflect.Type)

func (*Endpoint) SetTagsFromPath

func (e *Endpoint) SetTagsFromPath(path string)

type Handler

type Handler struct {
	// contains filtered or unexported fields
}

func NewHandler

func NewHandler(docs *Docs) *Handler

func (*Handler) Docs

func (h *Handler) Docs(ctx *gin.Context)

func (*Handler) JsonFile

func (h *Handler) JsonFile(ctx *gin.Context)

func (*Handler) YamlFile

func (h *Handler) YamlFile(ctx *gin.Context)

type Options

type Options struct {
	// ExtensionProps OpenAPI extensions.
	// It reads/writes all properties with prefix "x-".
	// It is empty as default.
	ExtensionProps map[string]interface{}

	// Title of the documentation.
	// If not set, the default value is "Documentation".
	Title string

	// Description of the documentation.
	// It is empty as default.
	Description string

	// TermsOfService usually should contain the URL to terms of service.
	// It is empty as default.
	TermsOfService string

	// Contact information must be in openAPI format.
	// It is empty as default.
	Contact *openapi3.Contact

	// License information must be in openAPI format.
	// It is empty as default.
	License *openapi3.License

	// Version of the documentation.
	// If not set, the default value is "1.0.0".
	Version string

	// InteractiveUrl is the path where your interactive documentation will be placed. It must be an absolute path, started with "/".
	// If you run the server locally, then your interactive docs will be under "http://localhost:<port><InteractiveUrl>".
	// If set to NoUrl, the interactive documentation will not be served.
	// If not set, the default value is "/docs".
	//
	// Interactive documentation uses the JSON file, thus it requires the JsonUrl is set to a valid url.
	// If the JsonUrl is set to NoUrl, the interactive documentation will be disabled.
	InteractiveUrl string

	// JsonUrl is the path where your openAPI in JSON format will be placed. It must be an absolute path, started with "/".
	// If you run the server locally, then the file will be under "http://localhost:<port><JsonUrl>".
	// If set to NoUrl, the json file will not be served.
	// If not set, the default value is "/docs.json".
	JsonUrl string

	// YamlUrl is the path where your openAPI in YAML format will be placed. It must be an absolute path, started with "/".
	// If you run the server locally, then the file will be under "http://localhost:<port><YamlUrl>".
	// If set to NoUrl, the yaml file will not be served.
	// If not set, the default value is "/docs.yaml".
	YamlUrl string

	// Servers is the list of the API locations. In interactive documentation (see InteractiveUrl) you can try your API out using one of those servers.
	// In case it is an empty list, it will be empty.
	// In case it is nil, the default value is a list with one element "http://localhost:8080".
	Servers []string

	// Tags for the documentation.
	// It is empty as default.
	Tags []string

	// Components is specified by OpenAPI/Swagger standard version 3.
	// It is empty as default.
	Components *openapi3.Components

	// Security is specified by OpenAPI/Swagger standard version 3.
	// It is empty as default.
	Security openapi3.SecurityRequirements
}

Options is used to initialize the documentation for new router. It simplifies some of the OpenAPI options like Servers or Tags. If you have some complex, custom configuration and need more control over your docs, you can update Docs.OpenApi directly.