Documentation
¶
Overview ¶
Package openapi is part of the GoFastr framework. See https://github.com/DonaldMurillo/gofastr for documentation.
Index ¶
- func DocsHandler(spec *Spec, basePath string, public bool) http.Handler
- 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
- 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) AddSecurity(name string, scopes []string)
- 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 DocsHandler ¶ added in v0.55.0
DocsHandler 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.
public controls the gate for BOTH the landing page and the nested spec route: an app that published its spec (framework's WithPublicOpenAPI) gets a browsable docs page to match, and an app that kept the spec private keeps the page private too. Splitting the two was the old behavior and it made the public spec unbrowsable.
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).
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
Security []map[string][]string
}
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) AddSecurity ¶ added in v0.14.0
AddSecurity appends a security requirement to the operation: the named scheme (with the given OAuth scopes, or no scopes for bearer/cookie auth) authorises the call. A nil scopes slice is normalised to an empty slice so JSON serialises as [] rather than null.
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) AddSchema ¶
AddSchema registers a reusable schema component. Registering the same name twice panics: a collision means two entities (or two versions of one entity) produced the same component key, and silent overwrite would leave $ref pointing at the wrong schema. The caller must disambiguate before building the spec (e.g. via a version slug in the component name).
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