Documentation ¶
Overview ¶
Package openapi provides helper functions to use github.com/swaggest/openapi-go/openapi3 more easily.
It also provides you with a set of rapidoc handlers to serve a live documentation of your API with rapidoc interface.
## How to add the rapidoc handlers
import ( "github.com/gorilla/mux" "github.com/mwm-io/gapi/openapi" ) // your router with routes. var r *mux.Router err := openapi.AddRapidocHandlers(r, openapi.config{}) if err != nil { log.Printf("error while adding rapidoc %+v\n", err) }
## How to document your handlers.
// your handler type MyHandler struct{} // Doc implements the openapi.Documented interface func (m PathParameters) Doc(builder *openapi.DocBuilder) error { return builder.WithDescription("my handler description"). WithParams({ ObjectID string `path:"objectID"` IsFull bool `query:"is_full"` }). Error() }
Index ¶
- Constants
- Variables
- func BuildOperation(reflector *openapi3.Reflector, h interface{}, method, path string) error
- func NewRapiDocHandler(middlewares ...handler.Middleware) handler.Handler
- func NewRapiDocReceiverHandler(middlewares ...handler.Middleware) handler.Handler
- func PopulateReflector(reflector *openapi3.Reflector, r *mux.Router, ignoredPaths []string) error
- type Authorization
- type BuilderOption
- func WithDescription(description string) BuilderOption
- func WithExample(exampleName string, value interface{}, options ...BuilderOption) BuilderOption
- func WithHeaders(headers map[string]string) BuilderOption
- func WithMimeType(valueType string) BuilderOption
- func WithRedirect(statusCode int, location string) BuilderOption
- func WithStatusCode(statusCode int) BuilderOption
- type DocBuilder
- func (b *DocBuilder) Commit() *DocBuilder
- func (b *DocBuilder) Error() error
- func (b *DocBuilder) Operation() *openapi3.Operation
- func (b *DocBuilder) Reflector() *openapi3.Reflector
- func (b *DocBuilder) WithBody(body interface{}, options ...BuilderOption) *DocBuilder
- func (b *DocBuilder) WithBodyExample(value interface{}) *DocBuilder
- func (b *DocBuilder) WithDescription(description string) *DocBuilder
- func (b *DocBuilder) WithError(statusCode int, kind, message string, options ...BuilderOption) *DocBuilder
- func (b *DocBuilder) WithOperationID(operationID string) *DocBuilder
- func (b *DocBuilder) WithParams(body interface{}) *DocBuilder
- func (b *DocBuilder) WithResponse(output interface{}, options ...BuilderOption) *DocBuilder
- func (b *DocBuilder) WithSummary(summary string) *DocBuilder
- func (b *DocBuilder) WithTags(tags ...string) *DocBuilder
- type Documented
- type RapiDocHandler
- type RapiDocReceiverHandler
- type SpecOpenAPIHandler
Constants ¶
const ( // DefaultDocURI is the URI used to host documentation UI DefaultDocURI = "/" // DocPageTitle is the URI used to host documentation UI DocPageTitle = "Doc | API" // DefaultSpecOpenAPIURI is the URI used to host the openapi file generated by this package DefaultSpecOpenAPIURI = "/openapi.json" )
Variables ¶
var Config config
Config is the default doc generator config. You can update all fields to change :
- DocURI: the URI for the display of your documentation. - SpecOpenAPIURI: the URL for the json openapi definition of your API. - IgnoredPaths: the paths that shouldn't be included in the documentation. - Auth: your auth system to protect your documentation.
Functions ¶
func BuildOperation ¶
BuildOperation adds the given h to the openapi3.Reflector
func NewRapiDocHandler ¶
func NewRapiDocHandler(middlewares ...handler.Middleware) handler.Handler
NewRapiDocHandler build a new RapiDocHandler.
func NewRapiDocReceiverHandler ¶ added in v0.0.4
func NewRapiDocReceiverHandler(middlewares ...handler.Middleware) handler.Handler
NewRapiDocReceiverHandler build a new RapiDocReceiverHandler.
Types ¶
type Authorization ¶
type Authorization interface { Authorize(w http.ResponseWriter, r *http.Request) (bool, error) Login(w http.ResponseWriter, r *http.Request) (interface{}, error) }
Authorization is able to determine whether a request is allowed to access the documentation or not. It also provides a Login method to indicate how to login.
type BuilderOption ¶
type BuilderOption func(c *builderOptions)
BuilderOption can be used to override default value or add precision to documented element
func WithDescription ¶
func WithDescription(description string) BuilderOption
WithDescription adds a description to documented element
func WithExample ¶
func WithExample(exampleName string, value interface{}, options ...BuilderOption) BuilderOption
WithExample add an example to documented element
func WithHeaders ¶
func WithHeaders(headers map[string]string) BuilderOption
WithHeaders add headers the documented element.
func WithMimeType ¶
func WithMimeType(valueType string) BuilderOption
WithMimeType add precision about type/format (or override default value) to documented element
func WithRedirect ¶
func WithRedirect(statusCode int, location string) BuilderOption
WithRedirect add a redirection response to the documented element.
func WithStatusCode ¶
func WithStatusCode(statusCode int) BuilderOption
WithStatusCode override default status code to documented element
type DocBuilder ¶
type DocBuilder struct {
// contains filtered or unexported fields
}
DocBuilder is a builder to simplify the documentation of an operation
func NewDocBuilder ¶
func NewDocBuilder(reflector *openapi3.Reflector, method, path string) *DocBuilder
NewDocBuilder returns a new doc.DocBuilder
func (*DocBuilder) Commit ¶
func (b *DocBuilder) Commit() *DocBuilder
Commit submit pending changes and return errors that was generated when building the operation
func (*DocBuilder) Error ¶
func (b *DocBuilder) Error() error
Error return the error that was generated when building the operation
func (*DocBuilder) Operation ¶
func (b *DocBuilder) Operation() *openapi3.Operation
Operation return the openapi3.Operation used to compute doc for current operation
func (*DocBuilder) Reflector ¶
func (b *DocBuilder) Reflector() *openapi3.Reflector
Reflector return the openapi3.Reflector used to builds OpenAPI Schema with reflected structures for current operation.
func (*DocBuilder) WithBody ¶
func (b *DocBuilder) WithBody(body interface{}, options ...BuilderOption) *DocBuilder
WithBody configure a request body to the operation Allowed options : - WithDescription to add a description to body - WithExample to add example(s) as body TODO: Find a way to support non json body like CSV, files, multi part, url encoded ...
func (*DocBuilder) WithBodyExample ¶
func (b *DocBuilder) WithBodyExample(value interface{}) *DocBuilder
WithBodyExample set an example to request body to the operation
func (*DocBuilder) WithDescription ¶
func (b *DocBuilder) WithDescription(description string) *DocBuilder
WithDescription set a description (additional explanation) to the operation
func (*DocBuilder) WithError ¶
func (b *DocBuilder) WithError(statusCode int, kind, message string, options ...BuilderOption) *DocBuilder
WithError configure an error for current operation Allowed options : - WithDescription to add a description to error response
func (*DocBuilder) WithOperationID ¶ added in v0.2.9
func (b *DocBuilder) WithOperationID(operationID string) *DocBuilder
WithOperationID set an operationID to the operation
func (*DocBuilder) WithParams ¶
func (b *DocBuilder) WithParams(body interface{}) *DocBuilder
WithParams configure path and query parameters to the operation To set path parameters use a struct with 'path' tag To set query parameters use a struct with 'query' tag
func (*DocBuilder) WithResponse ¶
func (b *DocBuilder) WithResponse(output interface{}, options ...BuilderOption) *DocBuilder
WithResponse configure a response for current operation Allowed options : - WithDescription to add a description to response - WithExample to add example(s) as response - WithMimeType to set a custom contentType (default to json) - WithStatusCode to set a specific status code. Default value are 204 for nil value and 200 for non nil value
func (*DocBuilder) WithSummary ¶
func (b *DocBuilder) WithSummary(summary string) *DocBuilder
WithSummary set a Summary (Title) to the operation
func (*DocBuilder) WithTags ¶
func (b *DocBuilder) WithTags(tags ...string) *DocBuilder
WithTags set tags to the operation: used to organise you operation in sections
type Documented ¶
type Documented interface {
Doc(builder *DocBuilder) error
}
Documented is able to describe itself as an openapi3 operation
type RapiDocHandler ¶
type RapiDocHandler struct { handler.WithMiddlewares // contains filtered or unexported fields }
RapiDocHandler is a server.SpecOpenAPIHandler that will serve a html page with rapidoc loading the given openAPIJsonURL
func (RapiDocHandler) Serve ¶
func (h RapiDocHandler) Serve(_ http.ResponseWriter, _ *http.Request) (interface{}, error)
Serve implements the handler.Handler interface
type RapiDocReceiverHandler ¶
type RapiDocReceiverHandler struct {
handler.WithMiddlewares
}
RapiDocReceiverHandler is a server.SpecOpenAPIHandler that will serve the rapidoc oauth receiver
func (RapiDocReceiverHandler) Serve ¶ added in v0.0.4
func (h RapiDocReceiverHandler) Serve(_ http.ResponseWriter, _ *http.Request) (interface{}, error)
Serve implements the handler.Handler interface
type SpecOpenAPIHandler ¶
type SpecOpenAPIHandler struct { handler.WithMiddlewares // contains filtered or unexported fields }
SpecOpenAPIHandler is a server.SpecOpenAPIHandler that will return a json openapi definition of the given reflector.
func NewSpecOpenAPIHandler ¶
func NewSpecOpenAPIHandler(router *mux.Router, middlewares ...handler.Middleware) *SpecOpenAPIHandler
NewSpecOpenAPIHandler builds a new SpecOpenAPIHandler, serving the api definition from the openapi3.Reflector, and checking auth access with the given Authorization.
func (*SpecOpenAPIHandler) Serve ¶
func (h *SpecOpenAPIHandler) Serve(_ http.ResponseWriter, _ *http.Request) (interface{}, error)
Serve implements the handler.Handler interface