openapi

package
v0.2.10 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 19, 2023 License: MIT Imports: 10 Imported by: 1

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

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

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

func BuildOperation(reflector *openapi3.Reflector, h interface{}, method, path string) error

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.

func PopulateReflector 

func PopulateReflector(reflector *openapi3.Reflector, r *mux.Router, ignoredPaths []string) error

PopulateReflector will add all the router routes into the given openapi3.Reflector You can add ignoredPath to ignore some registered routes.

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.