Documentation
¶
Overview ¶
Package openapi builds an OpenAPI 3.0.3 document from runtime-registered routes and reflected request/response structs, and serves it together with a CDN-backed Swagger UI. Schemas are derived from json and github.com/go-playground/validator struct tags.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Components ¶
type Components struct {
Schemas map[string]*Schema `json:"schemas,omitempty"`
SecuritySchemes map[string]*SecurityScheme `json:"securitySchemes,omitempty"`
}
Components holds reusable schemas and security schemes.
type Document ¶
type Document struct {
OpenAPI string `json:"openapi"`
Info Info `json:"info"`
Paths map[string]*PathItem `json:"paths"`
Components *Components `json:"components,omitempty"`
}
Document is the root OpenAPI 3.0.3 document.
type Info ¶
type Info struct {
Title string `json:"title"`
Version string `json:"version"`
Description string `json:"description,omitempty"`
}
Info is the OpenAPI info object.
type MediaType ¶
type MediaType struct {
Schema *Schema `json:"schema,omitempty"`
}
MediaType pairs a content type with its schema.
type Op ¶
type Op struct {
Summary string
Description string
Tags []string
Request any
Response any
Query any
Status int // success status; 0 -> 200
Secured bool // require the bearerAuth scheme
}
Op describes one operation to register. Request/Response/Query are struct values (or nil) reflected into schemas.
type Operation ¶
type Operation struct {
Summary string `json:"summary,omitempty"`
Description string `json:"description,omitempty"`
Tags []string `json:"tags,omitempty"`
Parameters []Parameter `json:"parameters,omitempty"`
RequestBody *RequestBody `json:"requestBody,omitempty"`
Responses map[string]Response `json:"responses"`
Security []map[string][]string `json:"security,omitempty"`
}
Operation describes one method on a path.
type Parameter ¶
type Parameter struct {
Name string `json:"name"`
In string `json:"in"`
Required bool `json:"required,omitempty"`
Schema *Schema `json:"schema,omitempty"`
}
Parameter is a path or query parameter.
type PathItem ¶
type PathItem struct {
Get *Operation `json:"get,omitempty"`
Post *Operation `json:"post,omitempty"`
Put *Operation `json:"put,omitempty"`
Patch *Operation `json:"patch,omitempty"`
Delete *Operation `json:"delete,omitempty"`
Head *Operation `json:"head,omitempty"`
Options *Operation `json:"options,omitempty"`
}
PathItem holds the operations for a single path.
type RequestBody ¶
type RequestBody struct {
Required bool `json:"required,omitempty"`
Content map[string]MediaType `json:"content"`
}
RequestBody is a request body object.
type Response ¶
type Response struct {
Description string `json:"description"`
Content map[string]MediaType `json:"content,omitempty"`
}
Response is a single response object.
type Schema ¶
type Schema struct {
Ref string `json:"$ref,omitempty"`
Type string `json:"type,omitempty"`
Format string `json:"format,omitempty"`
Nullable bool `json:"nullable,omitempty"`
Properties map[string]*Schema `json:"properties,omitempty"`
Required []string `json:"required,omitempty"`
Items *Schema `json:"items,omitempty"`
AdditionalProperties *Schema `json:"additionalProperties,omitempty"`
Enum []any `json:"enum,omitempty"`
Minimum *float64 `json:"minimum,omitempty"`
Maximum *float64 `json:"maximum,omitempty"`
MinLength *int `json:"minLength,omitempty"`
MaxLength *int `json:"maxLength,omitempty"`
MinItems *int `json:"minItems,omitempty"`
MaxItems *int `json:"maxItems,omitempty"`
}
Schema is a JSON Schema (the OpenAPI 3.0 subset used here).
type SecurityScheme ¶
type SecurityScheme struct {
Type string `json:"type"`
Scheme string `json:"scheme,omitempty"`
BearerFormat string `json:"bearerFormat,omitempty"`
}
SecurityScheme describes an authentication scheme.
type Spec ¶
type Spec struct {
// contains filtered or unexported fields
}
Spec accumulates registered operations and builds an OpenAPI document.
func New ¶
New creates an empty spec with the given info.
Example ¶
package main
import (
"fmt"
"github.com/rahmadafandi/fibr/v2/openapi"
)
type createUserReq struct {
Email string `json:"email" validate:"required,email"`
}
type userResp struct {
ID int `json:"id"`
Email string `json:"email"`
}
func main() {
oapi := openapi.New(openapi.Info{Title: "Users API", Version: "1.0.0"}).WithBearerAuth()
oapi.Register("POST", "/users", openapi.Op{
Summary: "Create user",
Tags: []string{"users"},
Request: createUserReq{},
Response: userResp{},
Status: 201,
Secured: true,
})
doc := oapi.Build()
fmt.Println(doc.OpenAPI)
fmt.Println(doc.Info.Title)
}
Output: 3.0.3 Users API
func (*Spec) MarshalJSON ¶
MarshalJSON marshals the built document.
func (*Spec) Register ¶
Register records one operation under method+path. method is case-insensitive. Fiber-style ":param" / "*" path segments convert to OpenAPI "{param}". Returns the spec for chaining.
func (*Spec) SpecHandler ¶
SpecHandler serves the OpenAPI document as JSON. The document is marshaled once on first request and cached, so register all operations before serving.
Example ¶
package main
import (
"fmt"
"github.com/gofiber/fiber/v3"
"github.com/rahmadafandi/fibr/v2/openapi"
)
func main() {
oapi := openapi.New(openapi.Info{Title: "API", Version: "1.0.0"})
oapi.Register("GET", "/ping", openapi.Op{Summary: "Ping"})
app := fiber.New()
app.Get("/openapi.json", oapi.SpecHandler())
app.Get("/docs", oapi.UIHandler("/openapi.json"))
_ = app
fmt.Println("docs mounted")
}
Output: docs mounted
func (*Spec) WithBearerAuth ¶
WithBearerAuth registers an HTTP bearer (JWT) security scheme named "bearerAuth". Operations opt in via Op.Secured. Idempotent; returns the spec for chaining.
Source Files