docs(api): add AX usage examples

Co-Authored-By: Virgil <virgil@lethean.io>

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.

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