Documentation
¶
Overview ¶
Package openapi is part of the GoFastr framework. See https://github.com/DonaldMurillo/gofastr for documentation.
Index ¶
- func FieldToSchema(field schema.Field) map[string]any
- func FieldsToSchema(fields []schema.Field) map[string]any
- func GatedHandler(spec *Spec, allow func(*http.Request) bool) http.Handler
- func Handler(spec *Spec) http.Handler
- func PublicHandler(spec *Spec) http.Handler
- func SwaggerUIHandler(spec *Spec, basePath string) http.Handler
- type Operation
- func (o *Operation) AddParameter(name, location, description string, required bool, schema map[string]any)
- func (o *Operation) AddResponse(status int, description string, schema map[string]any)
- func (o *Operation) SetRequestBody(contentType string, schema map[string]any, required bool)
- func (o *Operation) ToMap() map[string]any
- type Spec
- func (s *Spec) AddPath(method, path string, op Operation)
- func (s *Spec) AddSchema(name string, schema map[string]any)
- func (s *Spec) AddSecurityRequirement(name string, scopes []string)
- func (s *Spec) AddServer(url, description string)
- func (s *Spec) AddTag(name, description string)
- func (s *Spec) Build() map[string]any
- func (s *Spec) SetSecurityScheme(name string, scheme map[string]any)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FieldToSchema ¶
FieldToSchema converts a single schema.Field into an OpenAPI-compatible JSON Schema object.
func FieldsToSchema ¶
FieldsToSchema converts a slice of Fields into a JSON Schema object suitable for use as an OpenAPI schema.
func GatedHandler ¶
GatedHandler wraps the OpenAPI spec handler in an authorisation predicate. Requests for which allow(r) returns false get 404 (not 401/403 — leaking that an OpenAPI endpoint exists is itself the disclosure we're trying to avoid). 404 keeps the existence of the endpoint indistinguishable from a vanilla missing route. The allow predicate is the only auth gate — the wrapped spec handler does NOT re-check the user context.
Typical use:
openapi.GatedHandler(spec, func(r *http.Request) bool {
u, ok := handler.GetUser(r.Context())
return ok && u.(*MyUser).IsAdmin()
})
func Handler ¶
Handler returns an http.Handler that serves the OpenAPI spec as JSON at the root path (typically mounted at /openapi.json or /docs/openapi.json).
The spec lists every registered route, so by default the handler requires an authenticated context (the framework's auth chain must have called handler.SetUser). Apps that want a public OpenAPI spec can wrap PublicHandler around the same spec.
func PublicHandler ¶
PublicHandler serves the spec without an auth check — use only when the spec is intentionally public. Most apps should prefer Handler (auth-gated) or GatedHandler (custom predicate).
func SwaggerUIHandler ¶
SwaggerUIHandler returns an http.Handler that serves a minimal, self-contained API spec landing page. The page links to the OpenAPI JSON; viewers like Swagger UI / Insomnia / Stoplight / Postman can load it. Earlier revisions embedded swagger-ui-dist via a public CDN — that pulled the docs page's supply chain into a third-party host (and broke offline / air-gapped deploys), so the CDN reference was removed. Hosts that want the interactive UI can vendor swagger-ui themselves and mount their own handler.
Types ¶
type Operation ¶
type Operation struct {
Summary string
Description string
OperationID string
Tags []string
Parameters []map[string]any
RequestBody *map[string]any
Responses map[int]map[string]any
}
Operation represents a single OpenAPI operation (e.g. GET /users).
func (*Operation) AddParameter ¶
func (o *Operation) AddParameter(name, location, description string, required bool, schema map[string]any)
AddParameter appends a parameter to the operation. location is one of "path", "query", "header", "cookie".
func (*Operation) AddResponse ¶
AddResponse registers a response for the given HTTP status code.
func (*Operation) SetRequestBody ¶
SetRequestBody sets the request body for the operation.
type Spec ¶
type Spec struct {
// contains filtered or unexported fields
}
Spec is a builder for an OpenAPI 3.1 specification.
func (*Spec) AddPath ¶
AddPath registers a path + method with an Operation. Path parameters in GoFastr format (/users/:id) are automatically converted to OpenAPI format (/users/{id}) and path parameters are added to the operation.
func (*Spec) AddSecurityRequirement ¶
AddSecurityRequirement adds a global security requirement.
func (*Spec) AddServer ¶
AddServer registers a server URL with an optional description. URLs that don't begin with a relative path ("/", "./") or one of http(s)/ ws(s) are dropped: a `javascript:`/`data:`/`file:` entry in a publicly served spec turns the docs page into a phishing platform when a viewer clicks the "Servers" picker.
Source Files