openapi

package
v0.2.13 Latest Latest
Warning

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

 Go to latest Published: Apr 27, 2026 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 BuildDocBuilder added in v0.2.13 

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

BuildDocBuilder creates a DocBuilder populated with documentation from the handler and its middlewares. It calls Doc() on all documented middlewares and the handler, adds the default 500 error, and commits the operation. The returned DocBuilder contains all metadata needed for both OpenAPI spec generation and MCP tool creation.

func NewDocBuilder 

func NewDocBuilder(reflector *openapi3.Reflector, method, path string) *DocBuilder

NewDocBuilder returns a new doc.DocBuilder

func (*DocBuilder) BodyPtr added in v0.2.13 

func (b *DocBuilder) BodyPtr() interface{}

BodyPtr returns the raw body struct pointer stored during WithBody.

func (*DocBuilder) Commit 

func (b *DocBuilder) Commit() *DocBuilder

Commit submit pending changes and return errors that was generated when building the operation

func (*DocBuilder) Description added in v0.2.13 

func (b *DocBuilder) Description() string

Description returns the operation description, or empty string if not set.

func (*DocBuilder) Error 

func (b *DocBuilder) Error() error

Error return the error that was generated when building the operation

func (*DocBuilder) HTTPMethod added in v0.2.13 

func (b *DocBuilder) HTTPMethod() string

HTTPMethod returns the HTTP method for this operation.

func (*DocBuilder) IsMCPEnabled added in v0.2.13 

func (b *DocBuilder) IsMCPEnabled() bool

IsMCPEnabled returns whether this operation should be exposed as an MCP tool. Returns true by default unless explicitly disabled.

func (*DocBuilder) MCPToolName added in v0.2.13 

func (b *DocBuilder) MCPToolName() string

MCPToolName returns the custom MCP tool name, or empty string if not set.

func (*DocBuilder) Operation 

func (b *DocBuilder) Operation() *openapi3.Operation

Operation return the openapi3.Operation used to compute doc for current operation

func (*DocBuilder) OperationID added in v0.2.13 

func (b *DocBuilder) OperationID() string

OperationID returns the operation ID, or empty string if not set.

func (*DocBuilder) ParamPtrs added in v0.2.13 

func (b *DocBuilder) ParamPtrs() []interface{}

ParamPtrs returns the raw parameter struct pointers stored during WithParams.

func (*DocBuilder) Path added in v0.2.13 

func (b *DocBuilder) Path() string

Path returns the URL path for this 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) ResponsePtr added in v0.2.13 

func (b *DocBuilder) ResponsePtr() interface{}

ResponsePtr returns the raw response struct pointer stored during WithResponse.

func (*DocBuilder) Summary added in v0.2.13 

func (b *DocBuilder) Summary() string

Summary returns the operation summary, or empty string if not set.

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) WithMCP added in v0.2.13 

func (b *DocBuilder) WithMCP(enabled bool) *DocBuilder

WithMCP sets whether this operation should be exposed as an MCP tool. Default is true for all documented operations.

func (*DocBuilder) WithMCPToolName added in v0.2.13 

func (b *DocBuilder) WithMCPToolName(name string) *DocBuilder

WithMCPToolName overrides the auto-generated MCP tool name.

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.