Documentation
¶
Overview ¶
Package example provides OpenAPI Example Object support.
Examples demonstrate expected request/response formats for API documentation. They can contain inline values or reference external URLs.
Basic usage:
import "github.com/talav/openapi/example"
// Create an inline example
example.New("user-found", map[string]any{"id": 42, "status": "active"})
// Add descriptive metadata
example.New("error-case", map[string]any{"error": "not found"},
example.WithSummary("Resource not found"),
example.WithDescription("Returned when the requested resource does not exist"),
)
// Reference an external example file
example.NewExternal("full-dataset", "https://example.com/data/full.json")
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Example ¶
type Example struct {
// contains filtered or unexported fields
}
Example represents an OpenAPI Example Object. https://spec.openapis.org/oas/v3.1.0#example-object
Examples contain either an inline value or an external URL reference. Per the spec, these two options are mutually exclusive.
func New ¶
New creates an example with an inline value.
The name serves as the key in the examples map and must be unique within the parent request body or response object.
The value will be serialized to JSON in the generated OpenAPI document. Use functional options to add summary and description metadata.
Examples:
example.New("success", map[string]any{"status": "ok"})
example.New("with-details", data, example.WithSummary("Detailed response"))
func NewExternal ¶
NewExternal creates an example that references an external URL.
This is useful for large examples that would bloat the specification, binary or XML content that cannot be embedded, or examples shared across multiple API specifications.
Examples:
example.NewExternal("large-payload", "https://example.com/samples/large.json")
example.NewExternal("xml-sample", "https://example.com/samples/data.xml",
example.WithSummary("XML response format"))
func (Example) Description ¶
Description returns the detailed description.
func (Example) ExternalValue ¶
ExternalValue returns the external URL, or empty string for inline examples.
func (Example) IsExternal ¶
IsExternal reports whether this example references an external URL.
type Option ¶
type Option func(*Example)
Option configures an Example using the functional options pattern.
func WithDescription ¶
WithDescription adds a detailed explanation to the example. Supports CommonMark formatting for rich text documentation.
func WithSummary ¶
WithSummary adds a short description to the example. This typically appears as a title in documentation tools like Swagger UI.
Source Files