Documentation
¶
Overview ¶
Package example provides types and constructors for OpenAPI Example Objects.
Examples can be attached to request bodies and responses to help API consumers understand expected data formats. Both inline values and external URLs are supported.
Usage:
import "rivaas.dev/openapi/example"
// Inline example
example.New("success", UserResponse{ID: 123, Name: "John"})
// With metadata
example.New("admin", UserResponse{ID: 1, Role: "admin"},
example.WithSummary("Admin user response"),
example.WithDescription("Users with admin role have elevated permissions"),
)
// External URL example
example.NewExternal("large", "https://api.example.com/examples/large.json",
example.WithSummary("Large dataset"),
)
Index ¶
Examples ¶
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. See: https://spec.openapis.org/oas/v3.1.0#example-object
An Example can contain either an inline value or a reference to an external URL. These are mutually exclusive per the OpenAPI specification.
func New ¶
New creates a named example with an inline value.
The name is used as the key in the OpenAPI examples map. It must be unique within the same request/response context.
Parameters:
- name: Unique identifier for this example
- value: The example value (will be serialized to JSON in the spec)
- opts: Optional configuration (summary, description)
Example:
example.New("success", UserResponse{ID: 123, Name: "John"})
example.New("admin", UserResponse{ID: 1, Role: "admin"},
example.WithSummary("Admin user"),
example.WithDescription("Has elevated permissions"),
)
Example ¶
ExampleNew demonstrates creating a named example.
package main
import (
"fmt"
"rivaas.dev/openapi/example"
)
func main() {
type User struct {
ID int `json:"id"`
Name string `json:"name"`
}
ex := example.New("success", User{ID: 123, Name: "John"})
fmt.Printf("Name: %s, Value: %+v\n", ex.Name(), ex.Value())
}
Output: Name: success, Value: {ID:123 Name:John}
Example (WithOptions) ¶
ExampleNew_withOptions demonstrates creating an example with options.
package main
import (
"fmt"
"rivaas.dev/openapi/example"
)
func main() {
ex := example.New("admin", map[string]any{"id": 1, "role": "admin"},
example.WithSummary("Admin user response"),
example.WithDescription("Users with admin role have elevated permissions"),
)
fmt.Printf("Summary: %s\n", ex.Summary())
}
Output: Summary: Admin user response
func NewExternal ¶
NewExternal creates a named example pointing to an external URL.
Use this for:
- Large examples that would bloat the spec
- Examples in formats that cannot be embedded (XML, binary)
- Shared examples across multiple specifications
Parameters:
- name: Unique identifier for this example
- url: URL pointing to the example content
- opts: Optional configuration (summary, description)
Example:
example.NewExternal("large", "https://api.example.com/examples/large.json")
example.NewExternal("xml-format", "https://api.example.com/examples/user.xml",
example.WithSummary("XML format response"),
)
Example ¶
ExampleNewExternal demonstrates creating an external example.
package main
import (
"fmt"
"rivaas.dev/openapi/example"
)
func main() {
ex := example.NewExternal("large-dataset", "https://api.example.com/examples/large.json",
example.WithSummary("Large response dataset"),
)
fmt.Printf("External: %v, URL: %s\n", ex.IsExternal(), ex.ExternalValue())
}
Output: External: true, URL: https://api.example.com/examples/large.json
func (Example) Description ¶
Description returns the detailed description.
func (Example) ExternalValue ¶
ExternalValue returns the URL to an external example. Returns empty string for inline examples.
func (Example) IsExternal ¶
IsExternal returns true if this example uses an external URL.
type Option ¶
type Option func(*Example)
Option configures an Example using the functional options pattern.
func WithDescription ¶
WithDescription sets a detailed description for the example.
CommonMark syntax is supported for rich text formatting. Use this for longer explanations that wouldn't fit in a summary.
Example:
example.New("admin", data,
example.WithDescription("Users with admin role have full system access.\n\n**Note:** Admin users can modify all resources."),
)
func WithSummary ¶
WithSummary sets a short description for the example.
The summary appears as the example title in Swagger UI and other documentation tools. It should be concise (one line).
Example:
example.New("success", data, example.WithSummary("Successful response"))
Source Files