docs(api): add AX examples to public APIs

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

bridge.go

@@ -43,6 +43,10 @@ type boundTool struct {
 }
 
 // NewToolBridge creates a bridge that mounts tool endpoints at basePath.
+//
+// Example:
+//
+//	bridge := api.NewToolBridge("/mcp")
 func NewToolBridge(basePath string) *ToolBridge {
 	return &ToolBridge{
 		basePath: basePath,
@@ -51,6 +55,10 @@ func NewToolBridge(basePath string) *ToolBridge {
 }
 
 // Add registers a tool with its HTTP handler.
+//
+// Example:
+//
+//	bridge.Add(api.ToolDescriptor{Name: "ping", Description: "Ping the service"}, handler)
 func (b *ToolBridge) Add(desc ToolDescriptor, handler gin.HandlerFunc) {
 	if validator := newToolInputValidator(desc.OutputSchema); validator != nil {
 		handler = wrapToolResponseHandler(handler, validator)
@@ -120,6 +128,10 @@ func (b *ToolBridge) DescribeIter() iter.Seq[RouteDescription] {
 }
 
 // Tools returns all registered tool descriptors.
+//
+// Example:
+//
+//	descs := bridge.Tools()
 func (b *ToolBridge) Tools() []ToolDescriptor {
 	descs := make([]ToolDescriptor, len(b.tools))
 	for i, t := range b.tools {

client.go

@@ -55,6 +55,10 @@ type openAPIParameter struct {
 type OpenAPIClientOption func(*OpenAPIClient)
 
 // WithSpec sets the filesystem path to the OpenAPI document.
+//
+// Example:
+//
+//	client := api.NewOpenAPIClient(api.WithSpec("./openapi.yaml"))
 func WithSpec(path string) OpenAPIClientOption {
 	return func(c *OpenAPIClient) {
 		c.specPath = path
@@ -62,6 +66,10 @@ func WithSpec(path string) OpenAPIClientOption {
 }
 
 // WithBaseURL sets the base URL used for outgoing requests.
+//
+// Example:
+//
+//	client := api.NewOpenAPIClient(api.WithBaseURL("https://api.example.com"))
 func WithBaseURL(baseURL string) OpenAPIClientOption {
 	return func(c *OpenAPIClient) {
 		c.baseURL = baseURL
@@ -69,6 +77,13 @@ func WithBaseURL(baseURL string) OpenAPIClientOption {
 }
 
 // WithBearerToken sets the Authorization bearer token used for requests.
+//
+// Example:
+//
+//	client := api.NewOpenAPIClient(
+//		api.WithBaseURL("https://api.example.com"),
+//		api.WithBearerToken("secret-token"),
+//	)
 func WithBearerToken(token string) OpenAPIClientOption {
 	return func(c *OpenAPIClient) {
 		c.bearerToken = token
@@ -76,6 +91,10 @@ func WithBearerToken(token string) OpenAPIClientOption {
 }
 
 // WithHTTPClient sets the HTTP client used to execute requests.
+//
+// Example:
+//
+//	client := api.NewOpenAPIClient(api.WithHTTPClient(http.DefaultClient))
 func WithHTTPClient(client *http.Client) OpenAPIClientOption {
 	return func(c *OpenAPIClient) {
 		c.httpClient = client

codegen.go

@@ -111,6 +111,12 @@ func SupportedLanguages() []string {
 }
 
 // SupportedLanguagesIter returns an iterator over supported SDK target languages in sorted order.
+//
+// Example:
+//
+//	for lang := range api.SupportedLanguagesIter() {
+//		fmt.Println(lang)
+//	}
 func SupportedLanguagesIter() iter.Seq[string] {
 	return slices.Values(SupportedLanguages())
 }

export.go

@@ -16,6 +16,10 @@ import (
 
 // ExportSpec generates the OpenAPI spec and writes it to w.
 // Format must be "json" or "yaml".
+//
+// Example:
+//
+//	_ = api.ExportSpec(os.Stdout, "yaml", builder, engine.Groups())
 func ExportSpec(w io.Writer, format string, builder *SpecBuilder, groups []RouteGroup) error {
 	data, err := builder.Build(groups)
 	if err != nil {
@@ -45,6 +49,10 @@ func ExportSpec(w io.Writer, format string, builder *SpecBuilder, groups []Route
 
 // ExportSpecToFile writes the spec to the given path.
 // The parent directory is created if it does not exist.
+//
+// Example:
+//
+//	_ = api.ExportSpecToFile("./api/openapi.yaml", "yaml", builder, engine.Groups())
 func ExportSpecToFile(path, format string, builder *SpecBuilder, groups []RouteGroup) error {
 	if err := coreio.Local.EnsureDir(filepath.Dir(path)); err != nil {
 		return coreerr.E("ExportSpecToFile", "create directory", err)

spec_registry.go

@@ -15,6 +15,10 @@ var specRegistry struct {
 // RegisterSpecGroups adds route groups to the package-level spec registry.
 // Nil groups are ignored. Registered groups are returned by RegisteredSpecGroups
 // in the order they were added.
+//
+// Example:
+//
+//	api.RegisterSpecGroups(api.NewToolBridge("/mcp"))
 func RegisterSpecGroups(groups ...RouteGroup) {
 	specRegistry.mu.Lock()
 	defer specRegistry.mu.Unlock()
@@ -32,6 +36,10 @@ func RegisterSpecGroups(groups ...RouteGroup) {
 
 // RegisteredSpecGroups returns a copy of the route groups registered for
 // CLI-generated OpenAPI documents.
+//
+// Example:
+//
+//	groups := api.RegisteredSpecGroups()
 func RegisteredSpecGroups() []RouteGroup {
 	specRegistry.mu.RLock()
 	defer specRegistry.mu.RUnlock()
@@ -43,6 +51,10 @@ func RegisteredSpecGroups() []RouteGroup {
 
 // ResetSpecGroups clears the package-level spec registry.
 // It is primarily intended for tests that need to isolate global state.
+//
+// Example:
+//
+//	api.ResetSpecGroups()
 func ResetSpecGroups() {
 	specRegistry.mu.Lock()
 	defer specRegistry.mu.Unlock()