Documentation
¶
Overview ¶
Package openapi generates OpenAPI 3.1 specifications from AuthSome engine metadata.
Index ¶
- func OperationTakesToken(op *Operation, schemes map[string]*SecurityScheme) bool
- type Components
- type Generator
- type GeneratorConfig
- type Info
- type MediaType
- type Operation
- type Parameter
- type PathItem
- type RequestBody
- type Response
- type Schema
- type SecurityRequirement
- type SecurityScheme
- type Server
- type Spec
- type Tag
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func OperationTakesToken ¶
func OperationTakesToken(op *Operation, schemes map[string]*SecurityScheme) bool
OperationTakesToken reports whether generated client methods for op should carry an explicit bearer-token parameter.
The three language generators (golang, typescript, dart) each used to answer this by matching the literal scheme name "bearerAuth". That silently dropped the token parameter from every operation secured with forge's WithGroupAuth("session", "session-cookie") — 87 of the 200 operations in the current spec — leaving them impossible to authenticate through any SDK. "session" is a bearer scheme: extractToken reads Authorization: Bearer first and only then falls back to the auth_token cookie.
The rule is deliberately a property of the scheme rather than its name: a scheme carries a token when it is declared as HTTP bearer. Adding a new name to a route is then enough, so long as specgen declares it, and a name nobody declared contributes nothing rather than quietly deciding the answer.
schemes is spec.Components.SecuritySchemes, which may be nil or may not declare every name an operation references.
Types ¶
type Components ¶
type Components struct {
Schemas map[string]*Schema `json:"schemas,omitempty"`
SecuritySchemes map[string]*SecurityScheme `json:"securitySchemes,omitempty"`
}
Components holds a set of reusable objects.
type Generator ¶
type Generator struct {
// contains filtered or unexported fields
}
Generator produces an OpenAPI 3.1 spec from AuthSome engine metadata.
func NewGenerator ¶
func NewGenerator(cfg GeneratorConfig) *Generator
NewGenerator creates a new OpenAPI spec generator.
type GeneratorConfig ¶
type GeneratorConfig struct {
// Title is the API title (default: "AuthSome API").
Title string
// Description is the API description.
Description string
// Version is the API version (default: "0.5.0").
Version string
// BasePath is the base path for all endpoints (default: "/v1/auth").
BasePath string
// ServerURL is the server URL for the spec.
ServerURL string
// EnabledPlugins lists which plugins are enabled (affects which paths are included).
EnabledPlugins []string
}
GeneratorConfig holds configuration for OpenAPI spec generation.
type Info ¶
type Info struct {
Title string `json:"title"`
Description string `json:"description,omitempty"`
Version string `json:"version"`
}
Info provides metadata about the API.
type MediaType ¶
type MediaType struct {
Schema *Schema `json:"schema"`
}
MediaType describes a media type with a schema.
type Operation ¶
type Operation struct {
Summary string `json:"summary,omitempty"`
Description string `json:"description,omitempty"`
OperationID string `json:"operationId,omitempty"`
Tags []string `json:"tags,omitempty"`
Security []SecurityRequirement `json:"security,omitempty"`
Parameters []Parameter `json:"parameters,omitempty"`
RequestBody *RequestBody `json:"requestBody,omitempty"`
Responses map[string]*Response `json:"responses"`
}
Operation describes a single API operation on a path.
type Parameter ¶
type Parameter struct {
Name string `json:"name"`
In string `json:"in"` // "query", "path", "header"
Description string `json:"description,omitempty"`
Required bool `json:"required,omitempty"`
Schema *Schema `json:"schema,omitempty"`
}
Parameter describes a single operation 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"`
}
PathItem describes operations available on a single path.
type RequestBody ¶
type RequestBody struct {
Description string `json:"description,omitempty"`
Required bool `json:"required,omitempty"`
Content map[string]MediaType `json:"content"`
}
RequestBody describes a single request body.
type Response ¶
type Response struct {
Description string `json:"description"`
Content map[string]MediaType `json:"content,omitempty"`
}
Response describes a single response from an API Operation.
type Schema ¶
type Schema struct {
Type string `json:"type,omitempty"`
Format string `json:"format,omitempty"`
Description string `json:"description,omitempty"`
Properties map[string]*Schema `json:"properties,omitempty"`
Required []string `json:"required,omitempty"`
Items *Schema `json:"items,omitempty"`
Ref string `json:"$ref,omitempty"`
Enum []string `json:"enum,omitempty"`
}
Schema is a simplified JSON Schema representation.
func (*Schema) UnmarshalJSON ¶
UnmarshalJSON reads a schema and folds forge's nullable reference wrapper back into a plain $ref.
Since forge v1.12.9 a pointer element ([]*Connection) or a field tagged nullable is described as oneOf a $ref and a null-only object. The generators know nothing about oneOf, so without this every such list would come out as []any, unknown[] or List<dynamic>. The SDKs already treat a referenced element as possibly absent (a pointer in Go), so the null branch carries nothing they need.
type SecurityRequirement ¶
SecurityRequirement identifies the security schemes required.
type SecurityScheme ¶
type SecurityScheme struct {
Type string `json:"type"`
Scheme string `json:"scheme,omitempty"`
BearerFormat string `json:"bearerFormat,omitempty"`
Description string `json:"description,omitempty"`
Name string `json:"name,omitempty"`
In string `json:"in,omitempty"` // "header", "query", "cookie"
}
SecurityScheme defines a security scheme.
type Spec ¶
type Spec struct {
OpenAPI string `json:"openapi"`
Info Info `json:"info"`
Servers []Server `json:"servers,omitempty"`
Paths map[string]*PathItem `json:"paths"`
Components *Components `json:"components,omitempty"`
Security []SecurityRequirement `json:"security,omitempty"`
Tags []Tag `json:"tags,omitempty"`
}
Spec represents an OpenAPI 3.1.0 specification document.
func LoadSpecFromFile ¶
LoadSpecFromFile reads a JSON-encoded OpenAPI spec from disk. This is used by the sdkgen CLI when --from-spec is provided, allowing the spec to be produced externally (e.g., by the specgen tool) rather than by the hardcoded generator.
func (*Spec) SecuritySchemes ¶
func (s *Spec) SecuritySchemes() map[string]*SecurityScheme
SecuritySchemes returns the declared security schemes, or nil when the spec carries no components block. Callers pass the result straight to OperationTakesToken, so it has to survive a spec with nothing declared.
Source Files