From 0984c2f48ab0b55da87f14ddcbf591f20bb39177 Mon Sep 17 00:00:00 2001
From: Virgil <virgil@lethean.io>
Date: Wed, 1 Apr 2026 23:25:54 +0000
Subject: [PATCH] docs(api): add AX usage examples

Co-Authored-By: Virgil <virgil@lethean.io>
---
 group.go   | 24 ++++++++++++++++++++++++
 options.go | 16 ++++++++++++++++
 2 files changed, 40 insertions(+)

diff --git a/group.go b/group.go
index d44acdf..7084d34 100644
--- a/group.go
+++ b/group.go
@@ -45,6 +45,19 @@ type DescribableGroupIter interface {
 }
 
 // RouteDescription describes a single endpoint for OpenAPI generation.
+//
+// Example:
+//
+//	rd := api.RouteDescription{
+//		Method:      "POST",
+//		Path:        "/users",
+//		Summary:     "Create a user",
+//		Description: "Creates a new user account.",
+//		Tags:        []string{"users"},
+//		StatusCode:  201,
+//		RequestBody: map[string]any{"type": "object"},
+//		Response:    map[string]any{"type": "object"},
+//	}
 type RouteDescription struct {
 	Method      string   // HTTP method: GET, POST, PUT, DELETE, PATCH
 	Path        string   // Path relative to BasePath, e.g. "/generate"
@@ -73,6 +86,17 @@ type RouteDescription struct {
 }
 
 // ParameterDescription describes an OpenAPI parameter for a route.
+//
+// Example:
+//
+//	param := api.ParameterDescription{
+//		Name:        "id",
+//		In:          "path",
+//		Description: "User identifier",
+//		Required:    true,
+//		Schema:      map[string]any{"type": "string"},
+//		Example:     "usr_123",
+//	}
 type ParameterDescription struct {
 	Name        string         // Parameter name.
 	In          string         // Parameter location: path, query, header, or cookie.
diff --git a/options.go b/options.go
index 2d9efa3..a54d562 100644
--- a/options.go
+++ b/options.go
@@ -140,6 +140,10 @@ func WithSwagger(title, description, version string) Option {
 
 // WithSwaggerTermsOfService adds the terms of service URL to the generated Swagger spec.
 // Empty strings are ignored.
+//
+// Example:
+//
+//	api.WithSwaggerTermsOfService("https://example.com/terms")
 func WithSwaggerTermsOfService(url string) Option {
 	return func(e *Engine) {
 		e.swaggerTermsOfService = url
@@ -148,6 +152,10 @@ func WithSwaggerTermsOfService(url string) Option {
 
 // WithSwaggerContact adds contact metadata to the generated Swagger spec.
 // Empty fields are ignored. Multiple calls replace the previous contact data.
+//
+// Example:
+//
+//	api.WithSwaggerContact("API Support", "https://example.com/support", "support@example.com")
 func WithSwaggerContact(name, url, email string) Option {
 	return func(e *Engine) {
 		e.swaggerContactName = name
@@ -159,6 +167,10 @@ func WithSwaggerContact(name, url, email string) Option {
 // WithSwaggerServers adds OpenAPI server metadata to the generated Swagger spec.
 // Empty strings are ignored. Multiple calls append and normalise the combined
 // server list so callers can compose metadata across options.
+//
+// Example:
+//
+//	api.WithSwaggerServers("https://api.example.com", "https://docs.example.com")
 func WithSwaggerServers(servers ...string) Option {
 	return func(e *Engine) {
 		e.swaggerServers = normaliseServers(append(e.swaggerServers, servers...))
@@ -181,6 +193,10 @@ func WithSwaggerLicense(name, url string) Option {
 // WithSwaggerExternalDocs adds top-level external documentation metadata to
 // the generated Swagger spec.
 // Empty URLs are ignored; the description is optional.
+//
+// Example:
+//
+//	api.WithSwaggerExternalDocs("Developer guide", "https://example.com/docs")
 func WithSwaggerExternalDocs(description, url string) Option {
 	return func(e *Engine) {
 		e.swaggerExternalDocsDescription = description