Documentation
¶
Overview ¶
Package swagger generates and serves an OpenAPI document from the routes registered in an Arandu application.
Index ¶
- Constants
- func GenerateJSON(routes []*fhttp.Route, registry *Registry, config Config) ([]byte, error)
- func PublishedPaths() []string
- type APIKeyLocation
- type Callback
- type Components
- type Config
- type Contact
- type Content
- type Document
- type Documenter
- type Encoding
- type Example
- type Extensions
- type ExternalDocumentation
- type HTMXConfig
- type Header
- type Info
- type License
- type Media
- type MediaType
- type Middleware
- type Module
- func (m *Module) Diagnose(context.Context) []string
- func (m *Module) ExampleComponent(name string, example Example) error
- func (m *Module) Generate() (*Document, error)
- func (m *Module) GenerateJSON() ([]byte, error)
- func (m *Module) Header(name string, header Header) error
- func (m *Module) Name() string
- func (m *Module) Parameter(name string, parameter Parameter) error
- func (m *Module) Publishes() []foundation.Publication
- func (m *Module) RequestBody(name string, body RequestBody) error
- func (m *Module) Response(name string, response Response) error
- func (m *Module) Route(route *fhttp.Route) *OperationBuilder
- func (m *Module) Routes(router *fhttp.Router)
- func (m *Module) Schema(name string, schema jsonschema.Type) error
- func (m *Module) SchemaComponent(name string, schema Schema) error
- func (m *Module) SecurityScheme(name string, scheme SecurityScheme) error
- type OAuthFlow
- type OAuthFlows
- type Operation
- type OperationBuilder
- func (b *OperationBuilder) CookieParameter(name string, schema jsonschema.Type, options ...ParameterOption) *OperationBuilder
- func (b *OperationBuilder) DefaultResponse(description string, media ...*Media) *OperationBuilder
- func (b *OperationBuilder) Deprecated() *OperationBuilder
- func (b *OperationBuilder) Description(description string) *OperationBuilder
- func (b *OperationBuilder) Extension(name string, value any) *OperationBuilder
- func (b *OperationBuilder) ExternalDocumentation(docs ExternalDocumentation) *OperationBuilder
- func (b *OperationBuilder) HeaderParameter(name string, schema jsonschema.Type, options ...ParameterOption) *OperationBuilder
- func (b *OperationBuilder) Hidden() *OperationBuilder
- func (b *OperationBuilder) Ignore() *OperationBuilder
- func (b *OperationBuilder) Methods(methods ...string) *OperationBuilder
- func (b *OperationBuilder) OperationID(id string) *OperationBuilder
- func (b *OperationBuilder) OperationIDFor(method, id string) *OperationBuilder
- func (b *OperationBuilder) ParameterRef(name string) *OperationBuilder
- func (b *OperationBuilder) PathParameter(name string, options ...ParameterOption) *OperationBuilder
- func (b *OperationBuilder) QueryParameter(name string, schema jsonschema.Type, options ...ParameterOption) *OperationBuilder
- func (b *OperationBuilder) RequestBody(media ...*Media) *OperationBuilder
- func (b *OperationBuilder) RequestBodyDescription(description string) *OperationBuilder
- func (b *OperationBuilder) RequestBodyRef(component string) *OperationBuilder
- func (b *OperationBuilder) Response(status int, description string, media ...*Media) *OperationBuilder
- func (b *OperationBuilder) ResponseHeader(status int, name string, header Header) *OperationBuilder
- func (b *OperationBuilder) ResponseRef(status int, component string) *OperationBuilder
- func (b *OperationBuilder) Security(name string, scopes ...string) *OperationBuilder
- func (b *OperationBuilder) SecurityAll(requirement SecurityRequirement) *OperationBuilder
- func (b *OperationBuilder) Summary(summary string) *OperationBuilder
- func (b *OperationBuilder) Tags(tags ...string) *OperationBuilder
- type Parameter
- type ParameterLocation
- type ParameterOption
- type ParameterStyle
- type PathItem
- type Paths
- type Reference
- type Registry
- func (r *Registry) ExampleComponent(name string, example Example) error
- func (r *Registry) Header(name string, header Header) error
- func (r *Registry) Parameter(name string, parameter Parameter) error
- func (r *Registry) RequestBody(name string, body RequestBody) error
- func (r *Registry) Response(name string, response Response) error
- func (r *Registry) Revision() uint64
- func (r *Registry) Route(route *fhttp.Route) *OperationBuilder
- func (r *Registry) Schema(name string, native jsonschema.Type) error
- func (r *Registry) SchemaComponent(name string, schema Schema) error
- func (r *Registry) SecurityScheme(name string, scheme SecurityScheme) error
- type RequestBody
- type Response
- type Responses
- type RouteFilter
- type RoutePredicate
- type Schema
- type SecurityRequirement
- type SecurityScheme
- func APIKey(name string, location APIKeyLocation) SecurityScheme
- func HTTPBasic() SecurityScheme
- func HTTPBearer(format string) SecurityScheme
- func MutualTLS() SecurityScheme
- func OAuth2(flows OAuthFlows) SecurityScheme
- func OpenIDConnect(discoveryURL string) SecurityScheme
- func SecuritySchemeRef(name string) SecurityScheme
- type SecuritySchemeType
- type Server
- type ServerVariable
- type SwaggerViewData
- func (d SwaggerViewData) BackTextOrDefault() string
- func (d SwaggerViewData) BackURLOrDefault() string
- func (d SwaggerViewData) BrandOrDefault() string
- func (d SwaggerViewData) FaviconOrDefault() string
- func (d SwaggerViewData) HomeURLOrDefault() string
- func (d SwaggerViewData) LogoURLOrDefault() string
- type Tag
- type Theme
- type ThemeLogo
Examples ¶
Constants ¶
const ( // DefaultUIPath is the documentation UI endpoint used when UIPath is empty. DefaultUIPath = "/docs" // DefaultSpecPath is the specification endpoint used when both UIPath and // SpecPath are empty. DefaultSpecPath = "/docs/openapi.json" )
Variables ¶
This section is empty.
Functions ¶
func GenerateJSON ¶
GenerateJSON builds, validates, and deterministically serializes an OpenAPI document as JSON.
Example ¶
package main
import (
"fmt"
"net/http"
fhttp "github.com/arandu-io/framework/http"
swagger "github.com/hyz-is/arandu-swagger"
)
func main() {
router := fhttp.NewRouter()
registry := swagger.NewRegistry()
route := router.Get("/health", func(w http.ResponseWriter, _ *http.Request) {
w.WriteHeader(http.StatusNoContent)
}).Name("health.show")
registry.Route(route).Response(http.StatusNoContent, "Service is healthy")
data, err := swagger.GenerateJSON(router.Routes(), registry, swagger.Config{
Title: "Example API",
Version: "1.0.0",
})
if err != nil {
panic(err)
}
fmt.Println(len(data) > 0)
}
Output: true
func PublishedPaths ¶ added in v0.4.0
func PublishedPaths() []string
PublishedPaths returns the files the module offers for publication.
Types ¶
type APIKeyLocation ¶
type APIKeyLocation string
APIKeyLocation identifies where an API key is carried in a request.
const ( // APIKeyInQuery carries an API key in the URL query string. APIKeyInQuery APIKeyLocation = "query" // APIKeyInHeader carries an API key in an HTTP header. APIKeyInHeader APIKeyLocation = "header" // APIKeyInCookie carries an API key in an HTTP cookie. APIKeyInCookie APIKeyLocation = "cookie" )
type Components ¶
type Components struct {
// Schemas contains reusable Schema Objects.
Schemas map[string]Schema `json:"schemas,omitempty"`
// Responses contains reusable Response Objects.
Responses map[string]*Response `json:"responses,omitempty"`
// Parameters contains reusable Parameter Objects.
Parameters map[string]*Parameter `json:"parameters,omitempty"`
// Examples contains reusable Example Objects.
Examples map[string]*Example `json:"examples,omitempty"`
// RequestBodies contains reusable Request Body Objects.
RequestBodies map[string]*RequestBody `json:"requestBodies,omitempty"`
// Headers contains reusable Header Objects.
Headers map[string]*Header `json:"headers,omitempty"`
// SecuritySchemes contains reusable Security Scheme Objects.
SecuritySchemes map[string]*SecurityScheme `json:"securitySchemes,omitempty"`
// Callbacks contains reusable Callback Objects.
Callbacks map[string]Callback `json:"callbacks,omitempty"`
// PathItems contains reusable Path Item Objects.
PathItems map[string]*PathItem `json:"pathItems,omitempty"`
// Extensions contains specification extensions for components.
Extensions Extensions `json:"-"`
}
Components contains reusable OpenAPI objects keyed by component name.
func (Components) MarshalJSON ¶
func (v Components) MarshalJSON() ([]byte, error)
MarshalJSON renders the components and their specification extensions.
type Config ¶
type Config struct {
// Enabled registers the configured documentation endpoints when true.
Enabled bool
// Title is the API title written to the OpenAPI Info Object.
Title string
// Version is the documented API version written to the OpenAPI Info Object.
Version string
// Summary is the short API summary written to the OpenAPI Info Object.
Summary string
// Description is the API description written to the OpenAPI Info Object.
Description string
// TermsOfService is the API terms-of-service URL.
TermsOfService string
// Contact describes the API contact.
Contact *Contact
// License describes the API license.
License *License
// Servers lists the API server alternatives.
Servers []Server
// Tags declares the document-level tag metadata.
Tags []Tag
// ExternalDocs links to additional API documentation.
ExternalDocs *ExternalDocumentation
// JSONSchemaDialect overrides the default OpenAPI 3.1 schema dialect URI.
// When empty, it defaults to "https://spec.openapis.org/oas/3.1/dialect/base".
JSONSchemaDialect string
// UIPath is the exact route serving the Swagger UI.
UIPath string
// SpecPath is the exact route serving the OpenAPI JSON document.
SpecPath string
// DisableUI prevents registration of the Swagger UI and its assets.
DisableUI bool
// DisableSpec prevents public registration of the OpenAPI JSON endpoint.
// It requires DisableUI because the embedded UI consumes that endpoint.
DisableSpec bool
// IncludeUndocumented includes a basic operation for eligible routes that
// were not explicitly registered with the Documenter.
IncludeUndocumented bool
// IncludeInternal allows internal Arandu routes to pass the default filter.
IncludeInternal bool
// Filter applies explicit route metadata and predicate filters.
Filter RouteFilter
// CacheSpec reuses serialized document bytes until registry or public route
// metadata changes.
CacheSpec bool
// PersistAuthorization asks Swagger UI to retain authorization data.
PersistAuthorization bool
// DisableTryItOut removes interactive request execution from Swagger UI.
DisableTryItOut bool
// Locale specifies the UI language and localization (e.g. "pt-BR", "en").
// When empty, it defaults to "en".
Locale string
// Translations supplies custom key-value translation mappings to override
// or extend Swagger UI text strings.
Translations map[string]string
// ViewName specifies the Kyse view name rendered for the UI endpoint.
// Defaults to "docs.swagger". If the view is not registered or fails to render,
// the embedded standalone HTML shell is served as fallback.
ViewName string
// Theme configures visual styling, dark mode, colors, branding, and HTMX behavior.
Theme Theme
// UIMiddleware wraps the UI and embedded asset handlers in declaration order.
UIMiddleware []Middleware
// SpecMiddleware wraps the OpenAPI JSON handler in declaration order.
SpecMiddleware []Middleware
}
Config controls document generation and the optional HTTP endpoints.
Documentation is opt-in: the zero value is disabled and valid. When Enabled is true, Title and Version identify the generated OpenAPI document. An empty UIPath defaults to DefaultUIPath. An empty SpecPath is placed below the effective UIPath as openapi.json.
type Contact ¶
type Contact struct {
// Name is the contact person's or organization's name.
Name string `json:"name,omitempty"`
// URL is a URL for the contact information.
URL string `json:"url,omitempty"`
// Email is the contact email address.
Email string `json:"email,omitempty"`
// Extensions contains specification extensions for the contact.
Extensions Extensions `json:"-"`
}
Contact identifies a point of contact for the API.
func (Contact) MarshalJSON ¶
MarshalJSON renders the contact and its specification extensions.
type Document ¶
type Document struct {
// OpenAPI is the semantic version of the OpenAPI specification.
OpenAPI string `json:"openapi"`
// Info contains API identification and ownership metadata.
Info Info `json:"info"`
// JSONSchemaDialect is the default dialect for Schema Objects.
JSONSchemaDialect string `json:"jsonSchemaDialect,omitempty"`
// Servers lists the target server alternatives for the API.
Servers []Server `json:"servers,omitempty"`
// Paths contains the API's HTTP operations.
Paths Paths `json:"paths"`
// Webhooks contains incoming operations initiated by the API provider.
Webhooks Paths `json:"webhooks,omitempty"`
// Components contains reusable OpenAPI objects.
Components *Components `json:"components,omitempty"`
// Security declares the default security requirements.
Security []SecurityRequirement `json:"security,omitzero"`
// Tags contains document-level metadata for operation tags.
Tags []Tag `json:"tags,omitempty"`
// ExternalDocs links to additional documentation for the API.
ExternalDocs *ExternalDocumentation `json:"externalDocs,omitempty"`
// Extensions contains specification extensions for the document.
Extensions Extensions `json:"-"`
}
Document is an OpenAPI 3.1 document.
func Generate ¶
Generate builds and validates an OpenAPI 3.1 document from a route-table snapshot, an instance registry, and typed configuration. It does not start a server and is suitable for tests, CI, and static export by application code.
func (Document) MarshalJSON ¶
MarshalJSON renders the document and appends its specification extensions.
type Documenter ¶
type Documenter interface {
Route(route *fhttp.Route) *OperationBuilder
}
Documenter is the smallest contract an application module needs in order to document the routes it registers.
type Encoding ¶
type Encoding struct {
// ContentType is the media type for this property.
ContentType string `json:"contentType,omitempty"`
// Headers adds headers associated with this property's encoding.
Headers map[string]*Header `json:"headers,omitempty"`
// Style controls serialization of the property value.
Style ParameterStyle `json:"style,omitempty"`
// Explode controls serialization of composite property values.
Explode *bool `json:"explode,omitempty"`
// AllowReserved permits reserved URI characters in the encoded value.
AllowReserved bool `json:"allowReserved,omitempty"`
// Extensions contains specification extensions for the encoding.
Extensions Extensions `json:"-"`
}
Encoding describes how one request-body property is serialized.
func (Encoding) MarshalJSON ¶
MarshalJSON renders the property encoding and its specification extensions.
type Example ¶
type Example struct {
// Ref is a reference to a reusable Example Object.
Ref string `json:"$ref,omitempty"`
// Summary is a short description of the example.
Summary string `json:"summary,omitempty"`
// Description is the full example description.
Description string `json:"description,omitempty"`
// Value is the embedded example value.
Value json.RawMessage `json:"value,omitempty"`
// ExternalValue is a URL containing the example value.
ExternalValue string `json:"externalValue,omitempty"`
// Extensions contains specification extensions for the example.
Extensions Extensions `json:"-"`
}
Example describes an example value, or references a reusable example component.
func (Example) MarshalJSON ¶
MarshalJSON renders the example and its specification extensions.
type Extensions ¶
type Extensions map[string]json.RawMessage
Extensions contains OpenAPI specification extensions keyed by an x- name. Values are raw JSON so an extension remains explicit without weakening the fixed OpenAPI objects to map[string]any.
type ExternalDocumentation ¶
type ExternalDocumentation struct {
// Description explains what the external documentation contains.
Description string `json:"description,omitempty"`
// URL is the target documentation URL.
URL string `json:"url"`
// Extensions contains specification extensions for the link.
Extensions Extensions `json:"-"`
}
ExternalDocumentation links an OpenAPI object to further documentation.
func (ExternalDocumentation) MarshalJSON ¶
func (v ExternalDocumentation) MarshalJSON() ([]byte, error)
MarshalJSON renders the external documentation and its extensions.
type HTMXConfig ¶ added in v0.4.0
type HTMXConfig struct {
// Enabled adds HTMX lifecycle support to Swagger UI initialization.
Enabled bool
// Boost controls whether the Swagger UI container sets hx-boost="false"
// to prevent HTMX from intercepting Swagger UI's internal buttons and forms.
// When Enabled is true, Boost defaults to true.
Boost bool
}
HTMXConfig configures HTMX compatibility behavior.
type Header ¶
type Header struct {
// Ref is a reference to a reusable Header Object.
Ref string `json:"$ref,omitempty"`
// Description explains the header's purpose.
Description string `json:"description,omitempty"`
// Required marks the header as mandatory.
Required bool `json:"required,omitempty"`
// Deprecated marks the header as deprecated.
Deprecated bool `json:"deprecated,omitempty"`
// Style controls serialization of the header value.
Style ParameterStyle `json:"style,omitempty"`
// Explode controls serialization of composite header values.
Explode *bool `json:"explode,omitempty"`
// Schema describes the header value.
Schema *Schema `json:"schema,omitempty"`
// Example is one example header value.
Example json.RawMessage `json:"example,omitempty"`
// Examples contains named header examples.
Examples map[string]*Example `json:"examples,omitempty"`
// Content describes a complex header using one media type.
Content Content `json:"content,omitempty"`
// Extensions contains specification extensions for the header.
Extensions Extensions `json:"-"`
}
Header describes an HTTP response header, or references a reusable header component.
func (Header) MarshalJSON ¶
MarshalJSON renders the header and its specification extensions.
type Info ¶
type Info struct {
// Title is the public API name.
Title string `json:"title"`
// Summary is a short description of the API.
Summary string `json:"summary,omitempty"`
// Description is the full API description.
Description string `json:"description,omitempty"`
// TermsOfService is the URL of the API terms of service.
TermsOfService string `json:"termsOfService,omitempty"`
// Contact identifies a point of contact for the API.
Contact *Contact `json:"contact,omitempty"`
// License identifies the API's license.
License *License `json:"license,omitempty"`
// Version is the documented API version.
Version string `json:"version"`
// Extensions contains specification extensions for the Info Object.
Extensions Extensions `json:"-"`
}
Info describes the API exposed by an OpenAPI document.
func (Info) MarshalJSON ¶
MarshalJSON renders the API information and its specification extensions.
type License ¶
type License struct {
// Name is the license name.
Name string `json:"name"`
// Identifier is the SPDX license expression.
Identifier string `json:"identifier,omitempty"`
// URL is a URL for the license text.
URL string `json:"url,omitempty"`
// Extensions contains specification extensions for the license.
Extensions Extensions `json:"-"`
}
License identifies the license used by the API.
func (License) MarshalJSON ¶
MarshalJSON renders the license and its specification extensions.
type Media ¶
type Media struct {
// contains filtered or unexported fields
}
Media is one request or response representation supplied to a builder. Its schema and examples are immutable snapshots.
func JSON ¶
func JSON(native jsonschema.Type) *Media
JSON returns an application/json representation using a native Hesape schema. Any snapshot failure is reported by generation with route context.
func JSONRef ¶
JSONRef returns an application/json representation referencing a named schema component.
func MediaOf ¶
func MediaOf(contentType string, native jsonschema.Type) *Media
MediaOf returns a representation with an explicit content type and native Hesape schema.
func MediaRef ¶
MediaRef returns a representation with an explicit content type and schema component reference.
func (*Media) NamedExample ¶
NamedExample snapshots a named example for this representation.
type MediaType ¶
type MediaType struct {
// Schema describes values carried by this media type.
Schema *Schema `json:"schema,omitempty"`
// Example is one example media value.
Example json.RawMessage `json:"example,omitempty"`
// Examples contains named media examples.
Examples map[string]*Example `json:"examples,omitempty"`
// Encoding describes serialization of request-body properties.
Encoding map[string]*Encoding `json:"encoding,omitempty"`
// Extensions contains specification extensions for the media type.
Extensions Extensions `json:"-"`
}
MediaType describes the representation carried by one content type.
func (MediaType) MarshalJSON ¶
MarshalJSON renders the media type and its specification extensions.
type Middleware ¶
Middleware wraps one of the HTTP handlers exposed by the package.
type Module ¶
type Module struct {
// contains filtered or unexported fields
}
Module is the Arandu module that owns one isolated documentation registry. It captures the application's shared router when Routes is called and generates the document lazily, after every application module has had an opportunity to register its routes.
func New ¶
New returns an independently configured Swagger module.
Example ¶
package main
import (
"fmt"
swagger "github.com/hyz-is/arandu-swagger"
)
func main() {
docs, err := swagger.New(swagger.Config{
Enabled: true,
Title: "Example API",
Version: "1.0.0",
Description: "HTTP API documentation.",
UIPath: "/docs",
SpecPath: "/docs/openapi.json",
})
if err != nil {
panic(err)
}
fmt.Println(docs.Name())
}
Output: swagger
func (*Module) ExampleComponent ¶
ExampleComponent registers a reusable OpenAPI example component on this module instance.
func (*Module) Generate ¶
Generate builds the current typed OpenAPI document from the captured router.
func (*Module) GenerateJSON ¶
GenerateJSON serializes the current OpenAPI document. When CacheSpec is enabled it shares the registry- and route-aware cache used by the HTTP endpoint.
func (*Module) Header ¶
Header registers a reusable OpenAPI header component on this module instance.
func (*Module) Parameter ¶
Parameter registers a reusable OpenAPI parameter component on this module instance.
func (*Module) Publishes ¶ added in v0.4.0
func (m *Module) Publishes() []foundation.Publication
Publishes declares the files this package offers, each at the path it takes relative to the root of the project.
func (*Module) RequestBody ¶
func (m *Module) RequestBody(name string, body RequestBody) error
RequestBody registers a reusable OpenAPI request-body component on this module instance.
func (*Module) Response ¶
Response registers a reusable OpenAPI response component on this module instance.
func (*Module) Route ¶
func (m *Module) Route(route *fhttp.Route) *OperationBuilder
Route returns the operation builder associated with an application route.
Example ¶
package main
import (
"fmt"
"net/http"
fhttp "github.com/arandu-io/framework/http"
"github.com/arandu-io/hesape/jsonschema"
swagger "github.com/hyz-is/arandu-swagger"
)
func main() {
docs, err := swagger.New(swagger.Config{
Enabled: true,
Title: "Example API",
Version: "1.0.0",
})
if err != nil {
panic(err)
}
if err := docs.Schema("User", jsonschema.Object(
jsonschema.Prop("id", jsonschema.String().Format("uuid").Required()),
)); err != nil {
panic(err)
}
if err := docs.SecurityScheme("bearerAuth", swagger.HTTPBearer("JWT")); err != nil {
panic(err)
}
router := fhttp.NewRouter().ForModule("users")
route := router.Get("/api/users/{id}", func(http.ResponseWriter, *http.Request) {}).
Name("users.show").
WhereUuid("id")
docs.Route(route).
Summary("Show a user").
Tags("Users").
PathParameter("id", swagger.Description("User identifier.")).
Response(http.StatusOK, "User found", swagger.JSONRef("User")).
Security("bearerAuth")
docs.Routes(router.ForModule(docs.Name()))
document, err := docs.Generate()
if err != nil {
panic(err)
}
fmt.Println(document.OpenAPI, document.Paths["/api/users/{id}"].Get.OperationID)
}
Output: 3.1.0 users.show
func (*Module) Routes ¶
Routes captures the shared application router and registers the enabled specification and self-hosted UI endpoints.
func (*Module) Schema ¶
func (m *Module) Schema(name string, schema jsonschema.Type) error
Schema registers a reusable native Hesape JSON Schema component on this module instance.
func (*Module) SchemaComponent ¶
SchemaComponent registers an already snapshotted OpenAPI schema component on this module instance.
func (*Module) SecurityScheme ¶
func (m *Module) SecurityScheme(name string, scheme SecurityScheme) error
SecurityScheme registers a reusable OpenAPI security scheme component on this module instance.
type OAuthFlow ¶
type OAuthFlow struct {
// AuthorizationURL is the endpoint where a user grants authorization.
AuthorizationURL string `json:"authorizationUrl,omitempty"`
// TokenURL is the endpoint used to obtain tokens.
TokenURL string `json:"tokenUrl,omitempty"`
// RefreshURL is the endpoint used to refresh tokens.
RefreshURL string `json:"refreshUrl,omitempty"`
// Scopes maps OAuth scope names to their descriptions.
Scopes map[string]string `json:"scopes"`
// Extensions contains specification extensions for the flow.
Extensions Extensions `json:"-"`
}
OAuthFlow describes the endpoints and scopes for one OAuth 2.0 flow.
func (OAuthFlow) MarshalJSON ¶
MarshalJSON renders the OAuth flow and its specification extensions.
type OAuthFlows ¶
type OAuthFlows struct {
// Implicit describes an OAuth 2.0 implicit flow.
Implicit *OAuthFlow `json:"implicit,omitempty"`
// Password describes an OAuth 2.0 resource owner password flow.
Password *OAuthFlow `json:"password,omitempty"`
// ClientCredentials describes an OAuth 2.0 client credentials flow.
ClientCredentials *OAuthFlow `json:"clientCredentials,omitempty"`
// AuthorizationCode describes an OAuth 2.0 authorization code flow.
AuthorizationCode *OAuthFlow `json:"authorizationCode,omitempty"`
// Extensions contains specification extensions for the flow collection.
Extensions Extensions `json:"-"`
}
OAuthFlows contains the OAuth 2.0 flows supported by a security scheme.
func (OAuthFlows) MarshalJSON ¶
func (v OAuthFlows) MarshalJSON() ([]byte, error)
MarshalJSON renders the OAuth flows and their specification extensions.
type Operation ¶
type Operation struct {
// Tags groups the operation for readers and tooling.
Tags []string `json:"tags,omitempty"`
// Summary is a short description of the operation.
Summary string `json:"summary,omitempty"`
// Description is the full operation description.
Description string `json:"description,omitempty"`
// ExternalDocs links to additional operation documentation.
ExternalDocs *ExternalDocumentation `json:"externalDocs,omitempty"`
// OperationID uniquely identifies the operation in this document.
OperationID string `json:"operationId,omitempty"`
// Parameters contains path, query, header, and cookie parameters.
Parameters []*Parameter `json:"parameters,omitempty"`
// RequestBody describes the optional request body.
RequestBody *RequestBody `json:"requestBody,omitempty"`
// Responses contains the operation's possible responses.
Responses Responses `json:"responses"`
// Callbacks contains callbacks initiated by this operation.
Callbacks map[string]Callback `json:"callbacks,omitempty"`
// Deprecated marks the operation as deprecated.
Deprecated bool `json:"deprecated,omitempty"`
// Security overrides the document security requirements.
Security []SecurityRequirement `json:"security,omitzero"`
// Servers overrides the document servers for this operation.
Servers []Server `json:"servers,omitempty"`
// Extensions contains specification extensions for the operation.
Extensions Extensions `json:"-"`
}
Operation describes one HTTP operation on a path.
func (Operation) MarshalJSON ¶
MarshalJSON renders the operation and its specification extensions.
type OperationBuilder ¶
type OperationBuilder struct {
// contains filtered or unexported fields
}
OperationBuilder documents one registered route. Its methods are safe to call concurrently, although normal applications use it only during boot.
func (*OperationBuilder) CookieParameter ¶
func (b *OperationBuilder) CookieParameter(name string, schema jsonschema.Type, options ...ParameterOption) *OperationBuilder
CookieParameter documents a cookie parameter with a native schema.
func (*OperationBuilder) DefaultResponse ¶
func (b *OperationBuilder) DefaultResponse(description string, media ...*Media) *OperationBuilder
DefaultResponse declares the operation's default response.
func (*OperationBuilder) Deprecated ¶
func (b *OperationBuilder) Deprecated() *OperationBuilder
Deprecated marks the operation deprecated even when the route itself has no deprecation dates.
func (*OperationBuilder) Description ¶
func (b *OperationBuilder) Description(description string) *OperationBuilder
Description sets the operation's long description.
func (*OperationBuilder) Extension ¶
func (b *OperationBuilder) Extension(name string, value any) *OperationBuilder
Extension sets an x-* operation extension after snapshotting its JSON value.
func (*OperationBuilder) ExternalDocumentation ¶
func (b *OperationBuilder) ExternalDocumentation(docs ExternalDocumentation) *OperationBuilder
ExternalDocumentation attaches further documentation to the operation.
func (*OperationBuilder) HeaderParameter ¶
func (b *OperationBuilder) HeaderParameter(name string, schema jsonschema.Type, options ...ParameterOption) *OperationBuilder
HeaderParameter documents a request-header parameter with a native schema.
func (*OperationBuilder) Hidden ¶
func (b *OperationBuilder) Hidden() *OperationBuilder
Hidden excludes the operation from every generated document.
func (*OperationBuilder) Ignore ¶
func (b *OperationBuilder) Ignore() *OperationBuilder
Ignore is an alias for Hidden.
func (*OperationBuilder) Methods ¶
func (b *OperationBuilder) Methods(methods ...string) *OperationBuilder
Methods explicitly maps an ANY route, or a subset of a multi-method route, to concrete OpenAPI methods.
func (*OperationBuilder) OperationID ¶
func (b *OperationBuilder) OperationID(id string) *OperationBuilder
OperationID sets the operation identifier for a single-method route. Multi-method routes should use OperationIDFor or automatic method-qualified identifiers.
func (*OperationBuilder) OperationIDFor ¶
func (b *OperationBuilder) OperationIDFor(method, id string) *OperationBuilder
OperationIDFor sets the operation identifier for one concrete HTTP method of a multi-method route.
func (*OperationBuilder) ParameterRef ¶
func (b *OperationBuilder) ParameterRef(name string) *OperationBuilder
ParameterRef adds a reference to a reusable parameter component.
func (*OperationBuilder) PathParameter ¶
func (b *OperationBuilder) PathParameter(name string, options ...ParameterOption) *OperationBuilder
PathParameter documents a parameter already present in the route path.
func (*OperationBuilder) QueryParameter ¶
func (b *OperationBuilder) QueryParameter(name string, schema jsonschema.Type, options ...ParameterOption) *OperationBuilder
QueryParameter documents a query-string parameter with a native schema.
func (*OperationBuilder) RequestBody ¶
func (b *OperationBuilder) RequestBody(media ...*Media) *OperationBuilder
RequestBody sets the operation request body from one or more media types.
func (*OperationBuilder) RequestBodyDescription ¶
func (b *OperationBuilder) RequestBodyDescription(description string) *OperationBuilder
RequestBodyDescription sets the request body description, creating an empty body draft when necessary so generation can report missing content clearly.
func (*OperationBuilder) RequestBodyRef ¶
func (b *OperationBuilder) RequestBodyRef(component string) *OperationBuilder
RequestBodyRef sets the operation request body to a reusable request-body component.
func (*OperationBuilder) Response ¶
func (b *OperationBuilder) Response(status int, description string, media ...*Media) *OperationBuilder
Response declares a concrete HTTP status response.
func (*OperationBuilder) ResponseHeader ¶
func (b *OperationBuilder) ResponseHeader(status int, name string, header Header) *OperationBuilder
ResponseHeader adds a header to a previously declared response. It may be called first; generation then reports a missing response description.
func (*OperationBuilder) ResponseRef ¶
func (b *OperationBuilder) ResponseRef(status int, component string) *OperationBuilder
ResponseRef declares a response that references a reusable response component.
func (*OperationBuilder) Security ¶
func (b *OperationBuilder) Security(name string, scopes ...string) *OperationBuilder
Security adds one alternative security requirement. Calling it more than once creates OpenAPI OR alternatives; pass multiple schemes to SecurityAll for an AND requirement.
func (*OperationBuilder) SecurityAll ¶
func (b *OperationBuilder) SecurityAll(requirement SecurityRequirement) *OperationBuilder
SecurityAll adds one security requirement containing every supplied scheme.
func (*OperationBuilder) Summary ¶
func (b *OperationBuilder) Summary(summary string) *OperationBuilder
Summary sets the operation's short summary.
func (*OperationBuilder) Tags ¶
func (b *OperationBuilder) Tags(tags ...string) *OperationBuilder
Tags replaces the operation's explicit tags.
type Parameter ¶
type Parameter struct {
// Ref is a reference to a reusable Parameter Object.
Ref string `json:"$ref,omitempty"`
// Name is the case-sensitive parameter name.
Name string `json:"name,omitempty"`
// In identifies the request location carrying the parameter.
In ParameterLocation `json:"in,omitempty"`
// Description explains the parameter's purpose.
Description string `json:"description,omitempty"`
// Required marks a parameter as mandatory.
Required bool `json:"required,omitempty"`
// Deprecated marks the parameter as deprecated.
Deprecated bool `json:"deprecated,omitempty"`
// AllowEmptyValue permits an empty query parameter value.
AllowEmptyValue bool `json:"allowEmptyValue,omitempty"`
// Style controls serialization of the parameter value.
Style ParameterStyle `json:"style,omitempty"`
// Explode controls whether composite values use separate parameters.
Explode *bool `json:"explode,omitempty"`
// AllowReserved permits reserved URI characters in a query value.
AllowReserved bool `json:"allowReserved,omitempty"`
// Schema describes the parameter value.
Schema *Schema `json:"schema,omitempty"`
// Example is one example parameter value.
Example json.RawMessage `json:"example,omitempty"`
// Examples contains named parameter examples.
Examples map[string]*Example `json:"examples,omitempty"`
// Content describes a complex parameter using one media type.
Content Content `json:"content,omitempty"`
// Extensions contains specification extensions for the parameter.
Extensions Extensions `json:"-"`
}
Parameter describes one operation or path parameter, or references a reusable parameter component.
func (Parameter) MarshalJSON ¶
MarshalJSON renders the parameter and its specification extensions.
type ParameterLocation ¶
type ParameterLocation string
ParameterLocation is the part of a request that carries a parameter.
const ( // ParameterInQuery places a parameter in the URL query string. ParameterInQuery ParameterLocation = "query" // ParameterInHeader places a parameter in an HTTP header. ParameterInHeader ParameterLocation = "header" // ParameterInPath places a parameter in the URL path template. ParameterInPath ParameterLocation = "path" // ParameterInCookie places a parameter in an HTTP cookie. ParameterInCookie ParameterLocation = "cookie" )
type ParameterOption ¶
type ParameterOption func(*parameterSettings) error
ParameterOption changes an explicitly documented operation parameter.
func Description ¶
func Description(description string) ParameterOption
Description returns an option that describes a parameter.
func ExampleValue ¶
func ExampleValue(value any) ParameterOption
ExampleValue returns an option that snapshots one parameter example.
func ParameterDeprecated ¶
func ParameterDeprecated() ParameterOption
ParameterDeprecated returns an option that marks a parameter deprecated.
func ParameterRequired ¶
func ParameterRequired() ParameterOption
ParameterRequired returns an option that marks a non-path parameter as required. Path parameters are always required regardless of this option.
func ParameterSchema ¶
func ParameterSchema(native jsonschema.Type) ParameterOption
ParameterSchema returns an option that uses a native Hesape schema.
func ParameterSchemaRef ¶
func ParameterSchemaRef(name string) ParameterOption
ParameterSchemaRef returns an option that references a reusable schema.
type ParameterStyle ¶
type ParameterStyle string
ParameterStyle controls how a parameter is serialized.
const ( // ParameterStyleMatrix uses semicolon-prefixed path parameters. ParameterStyleMatrix ParameterStyle = "matrix" // ParameterStyleLabel uses dot-prefixed path parameters. ParameterStyleLabel ParameterStyle = "label" // ParameterStyleForm uses conventional query or cookie serialization. ParameterStyleForm ParameterStyle = "form" // ParameterStyleSimple uses comma-separated path or header serialization. ParameterStyleSimple ParameterStyle = "simple" // ParameterStyleSpaceDelimited uses space-delimited array values. ParameterStyleSpaceDelimited ParameterStyle = "spaceDelimited" // ParameterStylePipeDelimited uses pipe-delimited array values. ParameterStylePipeDelimited ParameterStyle = "pipeDelimited" // ParameterStyleDeepObject uses bracketed query object properties. ParameterStyleDeepObject ParameterStyle = "deepObject" )
type PathItem ¶
type PathItem struct {
// Ref is a reference to a reusable Path Item Object.
Ref string `json:"$ref,omitempty"`
// Summary describes every operation on this path.
Summary string `json:"summary,omitempty"`
// Description explains every operation on this path.
Description string `json:"description,omitempty"`
// Get is the HTTP GET operation.
Get *Operation `json:"get,omitempty"`
// Put is the HTTP PUT operation.
Put *Operation `json:"put,omitempty"`
// Post is the HTTP POST operation.
Post *Operation `json:"post,omitempty"`
// Delete is the HTTP DELETE operation.
Delete *Operation `json:"delete,omitempty"`
// Options is the HTTP OPTIONS operation.
Options *Operation `json:"options,omitempty"`
// Head is the HTTP HEAD operation.
Head *Operation `json:"head,omitempty"`
// Patch is the HTTP PATCH operation.
Patch *Operation `json:"patch,omitempty"`
// Trace is the HTTP TRACE operation.
Trace *Operation `json:"trace,omitempty"`
// Servers overrides the document servers for this path.
Servers []Server `json:"servers,omitempty"`
// Parameters applies parameters to every operation on this path.
Parameters []*Parameter `json:"parameters,omitempty"`
// Extensions contains specification extensions for the path item.
Extensions Extensions `json:"-"`
}
PathItem describes the operations available at one path.
func (PathItem) MarshalJSON ¶
MarshalJSON renders the path item and its specification extensions.
type Reference ¶
type Reference struct {
// Ref is the reference URI.
Ref string `json:"$ref"`
// Summary overrides the referenced object's summary where supported.
Summary string `json:"summary,omitempty"`
// Description overrides the referenced object's description where supported.
Description string `json:"description,omitempty"`
// Extensions contains specification extensions for the reference.
Extensions Extensions `json:"-"`
}
Reference points to an OpenAPI component or another resolvable object.
func (Reference) MarshalJSON ¶
MarshalJSON renders the reference and its specification extensions.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry owns the route documentation and reusable OpenAPI components for one Swagger module instance.
A Registry is safe for concurrent registration and generation. Builders and native schemas are snapshotted at their registration boundary; callers must still finish mutating a Hesape route before the application starts serving.
func NewRegistry ¶
func NewRegistry() *Registry
NewRegistry returns an empty, instance-owned documentation registry.
func (*Registry) ExampleComponent ¶
ExampleComponent registers a named reusable OpenAPI example.
func (*Registry) RequestBody ¶
func (r *Registry) RequestBody(name string, body RequestBody) error
RequestBody registers a named reusable OpenAPI request body.
func (*Registry) Revision ¶
Revision returns the registry revision used to invalidate a generated document cache. Every successful mutation and every recorded error advances it.
func (*Registry) Route ¶
func (r *Registry) Route(route *fhttp.Route) *OperationBuilder
Route returns the fluent documentation builder associated with route. Calling Route twice for the same pointer continues the same operation draft.
func (*Registry) Schema ¶
func (r *Registry) Schema(name string, native jsonschema.Type) error
Schema registers a named reusable native Hesape JSON Schema snapshot. Repeating the same component is idempotent; changing its content is an error.
func (*Registry) SchemaComponent ¶
SchemaComponent registers an already snapshotted OpenAPI schema. Use SchemaFromJSON to import keywords that native Hesape builders cannot express.
func (*Registry) SecurityScheme ¶
func (r *Registry) SecurityScheme(name string, scheme SecurityScheme) error
SecurityScheme registers a named reusable OpenAPI security scheme.
type RequestBody ¶
type RequestBody struct {
// Ref is a reference to a reusable Request Body Object.
Ref string `json:"$ref,omitempty"`
// Description explains the request body.
Description string `json:"description,omitempty"`
// Content maps accepted media types to their representations.
Content Content `json:"content,omitempty"`
// Required marks the request body as mandatory.
Required bool `json:"required,omitempty"`
// Extensions contains specification extensions for the request body.
Extensions Extensions `json:"-"`
}
RequestBody describes the body of a request, or references a reusable request body component.
func (RequestBody) MarshalJSON ¶
func (v RequestBody) MarshalJSON() ([]byte, error)
MarshalJSON renders the request body and its specification extensions.
type Response ¶
type Response struct {
// Ref is a reference to a reusable Response Object.
Ref string `json:"$ref,omitempty"`
// Description explains the response.
Description string `json:"description,omitempty"`
// Headers contains response header metadata.
Headers map[string]*Header `json:"headers,omitempty"`
// Content maps returned media types to their representations.
Content Content `json:"content,omitempty"`
// Extensions contains specification extensions for the response.
Extensions Extensions `json:"-"`
}
Response describes an operation response, or references a reusable response component.
func (Response) MarshalJSON ¶
MarshalJSON renders the response and its specification extensions.
type RouteFilter ¶
type RouteFilter struct {
// IncludePrefixes allows routes whose paths start with one of these values.
IncludePrefixes []string
// ExcludePrefixes rejects routes whose paths start with one of these values.
ExcludePrefixes []string
// IncludeNames allows routes with one of these route names.
IncludeNames []string
// ExcludeNames rejects routes with one of these route names.
ExcludeNames []string
// IncludeModules allows routes owned by one of these module names.
IncludeModules []string
// ExcludeModules rejects routes owned by one of these module names.
ExcludeModules []string
// IncludeMethods allows routes using one of these HTTP methods.
IncludeMethods []string
// ExcludeMethods rejects routes using one of these HTTP methods.
ExcludeMethods []string
// IncludeDomains allows routes scoped to one of these domains.
IncludeDomains []string
// ExcludeDomains rejects routes scoped to one of these domains.
ExcludeDomains []string
// IncludePredicate applies an additional caller-defined allow rule.
IncludePredicate RoutePredicate
// ExcludePredicate applies an additional caller-defined deny rule.
ExcludePredicate RoutePredicate
}
RouteFilter limits which application routes may appear in the document.
A non-empty include list acts as an allowlist for that dimension. Exclusions are applied after inclusions. Prefixes match route paths; all other list fields match their route metadata. IncludePredicate must accept a route and ExcludePredicate must not reject it.
type RoutePredicate ¶
type RoutePredicate func(*frameworkhttp.Route) bool
RoutePredicate decides whether a route passes a caller-defined filter.
type Schema ¶
type Schema struct {
// contains filtered or unexported fields
}
Schema is an immutable OpenAPI schema snapshot or a schema reference. Native schema builders are snapshotted by SchemaFrom so later builder mutations cannot race with or alter document generation.
func SchemaFrom ¶
func SchemaFrom(native jsonschema.Type) (schema Schema, err error)
SchemaFrom snapshots a native Hesape JSON Schema type for use in OpenAPI. It returns an error when the type is nil, panics while marshaling, or does not produce a structurally valid JSON Schema object supported by this adapter.
func SchemaFromJSON ¶
SchemaFromJSON validates and snapshots one JSON-encoded OpenAPI Schema Object. Native Hesape builders remain the preferred construction path; this import boundary preserves schema keywords that their closed type set cannot represent.
func SchemaReference ¶
SchemaReference returns a schema that uses the exact reference supplied by the caller. Its URI-reference syntax is checked when marshaled and during document generation.
func (Schema) IsReference ¶
IsReference reports whether the schema is represented by a reference.
func (Schema) IsZero ¶
IsZero reports whether the schema contains neither a snapshot nor a reference.
func (Schema) JSON ¶
func (s Schema) JSON() json.RawMessage
JSON returns a copy of an inline schema snapshot. It returns nil for a reference or an empty schema.
func (Schema) MarshalJSON ¶
MarshalJSON renders the immutable schema snapshot or reference.
type SecurityRequirement ¶
SecurityRequirement maps a security scheme name to the scopes required from that scheme. An empty scope list is used by non-OAuth schemes.
func SecurityRequirementFor ¶
func SecurityRequirementFor(name string, scopes ...string) SecurityRequirement
SecurityRequirementFor builds one requirement for a named security scheme.
func (SecurityRequirement) MarshalJSON ¶
func (r SecurityRequirement) MarshalJSON() ([]byte, error)
MarshalJSON renders absent scopes as an empty JSON array, which is the OpenAPI representation required for non-OAuth security schemes.
type SecurityScheme ¶
type SecurityScheme struct {
// Ref is a reference to a reusable Security Scheme Object.
Ref string `json:"$ref,omitempty"`
// Type identifies the security scheme kind.
Type SecuritySchemeType `json:"type,omitempty"`
// Description explains how the security scheme is used.
Description string `json:"description,omitempty"`
// Name is the request value carrying an API key.
Name string `json:"name,omitempty"`
// In is the request location carrying an API key.
In APIKeyLocation `json:"in,omitempty"`
// Scheme is the HTTP Authorization scheme name.
Scheme string `json:"scheme,omitempty"`
// BearerFormat is a documentation hint for bearer token formatting.
BearerFormat string `json:"bearerFormat,omitempty"`
// Flows contains the supported OAuth 2.0 flows.
Flows *OAuthFlows `json:"flows,omitempty"`
// OpenIDConnectURL is the OpenID Connect discovery URL.
OpenIDConnectURL string `json:"openIdConnectUrl,omitempty"`
// Extensions contains specification extensions for the security scheme.
Extensions Extensions `json:"-"`
}
SecurityScheme describes an authentication mechanism, or references a reusable security scheme component.
func APIKey ¶
func APIKey(name string, location APIKeyLocation) SecurityScheme
APIKey builds a security scheme for an API key in a query, header, or cookie value.
func HTTPBasic ¶
func HTTPBasic() SecurityScheme
HTTPBasic builds an HTTP Basic authentication security scheme.
func HTTPBearer ¶
func HTTPBearer(format string) SecurityScheme
HTTPBearer builds an HTTP bearer security scheme.
func OAuth2 ¶
func OAuth2(flows OAuthFlows) SecurityScheme
OAuth2 builds an OAuth 2.0 security scheme from its supported flows.
func OpenIDConnect ¶
func OpenIDConnect(discoveryURL string) SecurityScheme
OpenIDConnect builds an OpenID Connect security scheme from its discovery URL.
func SecuritySchemeRef ¶
func SecuritySchemeRef(name string) SecurityScheme
SecuritySchemeRef returns a local reference to a named security scheme component.
func (SecurityScheme) MarshalJSON ¶
func (v SecurityScheme) MarshalJSON() ([]byte, error)
MarshalJSON renders the security scheme and its specification extensions.
type SecuritySchemeType ¶
type SecuritySchemeType string
SecuritySchemeType identifies an OpenAPI security scheme kind.
const ( // SecuritySchemeAPIKey authenticates with a named request value. SecuritySchemeAPIKey SecuritySchemeType = "apiKey" // SecuritySchemeHTTP authenticates with an HTTP authentication scheme. SecuritySchemeHTTP SecuritySchemeType = "http" // SecuritySchemeMutualTLS authenticates with mutual TLS. SecuritySchemeMutualTLS SecuritySchemeType = "mutualTLS" // SecuritySchemeOAuth2 authenticates through OAuth 2.0 flows. SecuritySchemeOAuth2 SecuritySchemeType = "oauth2" // SecuritySchemeOpenIDConnect authenticates through OpenID Connect discovery. SecuritySchemeOpenIDConnect SecuritySchemeType = "openIdConnect" )
type Server ¶
type Server struct {
// URL is the server URL or URL template.
URL string `json:"url"`
// Description explains the server's purpose.
Description string `json:"description,omitempty"`
// Variables defines substitutions used by the URL template.
Variables map[string]ServerVariable `json:"variables,omitempty"`
// Extensions contains specification extensions for the server.
Extensions Extensions `json:"-"`
}
Server describes one target server for the API.
func (Server) MarshalJSON ¶
MarshalJSON renders the server and its specification extensions.
type ServerVariable ¶
type ServerVariable struct {
// Enum limits the variable to an allowed set of values.
Enum []string `json:"enum,omitempty"`
// Default is the value used when no substitution is supplied.
Default string `json:"default"`
// Description explains the variable's purpose.
Description string `json:"description,omitempty"`
// Extensions contains specification extensions for the variable.
Extensions Extensions `json:"-"`
}
ServerVariable describes a substituted value in a server URL template.
func (ServerVariable) MarshalJSON ¶
func (v ServerVariable) MarshalJSON() ([]byte, error)
MarshalJSON renders the server variable and its specification extensions.
type SwaggerViewData ¶ added in v0.4.0
type SwaggerViewData struct {
view.Page
Version string
SpecPath string
UIPath string
Locale string
Favicon string
BackURL string
BackText string
BackTarget string
DisableThemeToggle bool
LogoURL string
LogoAlt string
LogoHref string
LogoTarget string
}
SwaggerViewData is the data payload provided to the Kyse view.
func (SwaggerViewData) BackTextOrDefault ¶ added in v0.4.0
func (d SwaggerViewData) BackTextOrDefault() string
BackTextOrDefault returns the back link label localized according to Locale.
func (SwaggerViewData) BackURLOrDefault ¶ added in v0.4.0
func (d SwaggerViewData) BackURLOrDefault() string
BackURLOrDefault returns the URL to return to the site, defaulting to HomeURLOrDefault.
func (SwaggerViewData) BrandOrDefault ¶ added in v0.4.0
func (d SwaggerViewData) BrandOrDefault() string
BrandOrDefault returns the brand name, preferring LogoAlt, then AppName, then Peráta.
func (SwaggerViewData) FaviconOrDefault ¶ added in v0.4.0
func (d SwaggerViewData) FaviconOrDefault() string
FaviconOrDefault returns the favicon path, defaulting to /favicon.ico.
func (SwaggerViewData) HomeURLOrDefault ¶ added in v0.4.0
func (d SwaggerViewData) HomeURLOrDefault() string
HomeURLOrDefault returns the home URL, preferring LogoHref, then HomeURL, then /.
func (SwaggerViewData) LogoURLOrDefault ¶ added in v0.4.0
func (d SwaggerViewData) LogoURLOrDefault() string
LogoURLOrDefault returns the logo URL, defaulting to /favicon.svg.
type Tag ¶
type Tag struct {
// Name is the tag used by operations.
Name string `json:"name"`
// Description explains the tagged group of operations.
Description string `json:"description,omitempty"`
// ExternalDocs links to additional documentation for the tag.
ExternalDocs *ExternalDocumentation `json:"externalDocs,omitempty"`
// Extensions contains specification extensions for the tag.
Extensions Extensions `json:"-"`
}
Tag adds metadata to an operation tag.
func (Tag) MarshalJSON ¶
MarshalJSON renders the tag and its specification extensions.
type Theme ¶ added in v0.4.0
type Theme struct {
// Title overrides the HTML document title. When empty, Config.Title is used.
Title string
// DarkMode enables the modern dark theme matching Fastify and Peráta styling.
DarkMode bool
// Locale specifies the UI language (e.g. "pt-BR", "en").
Locale string
// Translations supplies custom translation overrides.
Translations map[string]string
// ViewName specifies the Kyse view name rendered for the UI endpoint.
ViewName string
// PrimaryColor sets the accent color for buttons, badges, links, and highlights
// (e.g. "#14b8a6", "#5eead4", or any valid CSS color).
PrimaryColor string
// BackgroundColor overrides the page background color (default "#0a0a0a" in dark mode).
BackgroundColor string
// CardColor overrides the card/container background color (default "#121214" in dark mode).
CardColor string
// TextColor overrides the primary text color (default "#f4f4f5" in dark mode).
TextColor string
// MutedColor overrides subtle/secondary text (default "#a1a1aa" in dark mode).
MutedColor string
// BorderColor overrides borders (default "#27272a" in dark mode).
BorderColor string
// Logo configures an optional branding logo in the topbar header.
Logo *ThemeLogo
// BackURL configures the "Voltar para o site" link target in the topbar.
// When empty, defaults to ThemeLogo.Href or "/".
BackURL string
// BackText overrides the back link text (defaults to "Voltar para o site" for pt/pt-BR and "Back to site" for other locales).
BackText string
// BackTarget is the anchor target for the back link (defaults to "_self").
BackTarget string
// DisableThemeToggle hides the light/dark theme switch in the topbar.
DisableThemeToggle bool
// Favicon is the URL to a custom favicon (e.g. "/favicon.ico" or "/favicon.png").
Favicon string
// CustomCSS is custom CSS appended to the theme stylesheet.
CustomCSS string
// CustomJS is custom JavaScript served and executed on the page.
CustomJS string
// HTMX configures HTMX-specific compatibility options.
HTMX HTMXConfig
}
Theme controls visual styling, dark mode, custom colors, branding, and HTMX behavior.
type ThemeLogo ¶ added in v0.4.0
type ThemeLogo struct {
// URL is the image URL or data URI of the logo.
URL string
// Href is the link target when clicking the logo (defaults to "/").
Href string
// Alt is the alternative text for the logo (defaults to the API title).
Alt string
// Target is the anchor target, e.g. "_blank" or "_self" (defaults to "_self").
Target string
}
ThemeLogo configures the brand logo in the Swagger UI topbar.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
examples
|
|
|
basic
Package basic demonstrates explicit Arandu Swagger wiring and route-local documentation with native Hesape schemas.
|
Package basic demonstrates explicit Arandu Swagger wiring and route-local documentation with native Hesape schemas. |
|
static
command
Command static-openapi generates OpenAPI JSON without starting an HTTP server.
|
Command static-openapi generates OpenAPI JSON without starting an HTTP server. |
|
internal
|
|
|
ui
Package ui provides the self-hosted Swagger UI distribution assets.
|
Package ui provides the self-hosted Swagger UI distribution assets. |