From fedb626c7b7eadac970a570286e25d4b76e1969b Mon Sep 17 00:00:00 2001 From: Ali KavianiHamedani Date: Thu, 19 Dec 2024 12:58:29 +0100 Subject: [PATCH] docs: update docs --- apis/doc.go | 108 ++++++++++++++++++++++++------------- client/doc.go | 66 +++++++++++++++++++++-- doc.go | 73 ++++++++++++++++++++----- models/{docs.go => doc.go} | 0 4 files changed, 191 insertions(+), 56 deletions(-) rename models/{docs.go => doc.go} (100%) diff --git a/apis/doc.go b/apis/doc.go index 592c941..448af47 100644 --- a/apis/doc.go +++ b/apis/doc.go @@ -1,46 +1,78 @@ // Package apis provides multiple APIs to interact with the Apicurio Registry. // -// The apis package exposes different high-level APIs to manage resources in the Apicurio Registry, -// such as artifacts, metadata, and administrative operations. Each API abstracts specific -// functionality of the Apicurio Registry, providing a clean and easy-to-use interface. +// The apis package exposes high-level APIs to manage resources in the Apicurio Registry, +// such as artifacts, versions, metadata, and administrative operations. Each API +// encapsulates specific functionalities of the Apicurio Registry, ensuring a modular and +// user-friendly interface. // // Available APIs: -// - AdminAPI: Provides administrative operations, such as clearing the cache and managing system-level settings. -// - ArtifactsAPI: Manages artifact lifecycles, including creation, retrieval, versioning, and deletion of schemas. -// - MetadataAPI: Handles schema metadata operations, such as tagging, labeling, and descriptions. -// - RulesAPI: Allows configuration and management of rules for compatibility and validation. -// - BranchesAPI: Allows configuration and management of branches for artifact versioning. -// - GroupsAPI: Manages groups related resource in apicurio registry. -// - VersionsAPI: Manages versions related resource in apicurio registry. -// - SystemsAPI: Manages systems related resource in apicurio registry. -// - ... -// -// Features: -// - Register, retrieve, and delete artifacts. -// - Perform schema versioning and compatibility checks. -// - Manage metadata, tags, and labels for artifacts. -// - Execute administrative actions on the Apicurio Registry. -// -// Example usage: -// -// import "github.com/mollie/go-apicurio-registry/apis" +// +// 1. **ArtifactsAPI**: Manages artifacts (schemas), including creation, retrieval, +// updating, and deletion. +// +// 2. **VersionsAPI**: Handles operations related to artifact versions, such as retrieving +// and managing version history. +// +// 3. **GroupsAPI**: Supports grouping of artifacts to enable multi-tenancy and +// organizational categorization. +// +// 4. **MetadataAPI**: Provides methods to manage artifact metadata and perform +// compatibility checks. +// +// 5. **AdminAPI**: Enables administrative operations like clearing caches, monitoring +// system health, and managing global settings. +// +// 6. **SystemAPI**: Offers methods for querying registry status and configuration. +// +// Example Usage: +// +// The following example demonstrates how to use the ArtifactsAPI to create and retrieve an artifact: +// +// package main +// +// import ( +// "fmt" +// "github.com/mollie/go-apicurio-registry/apis" +// "github.com/mollie/go-apicurio-registry/client" +// "github.com/mollie/go-apicurio-registry/models" +// ) // // func main() { -// // Initialize the Artifacts API -// artifactsAPI := apis.NewArtifactsAPI("https://registry.example.com") -// -// // Register a new artifact -// err := artifactsAPI.RegisterArtifact("example-subject", `{"type":"record","name":"example"}`) -// if err != nil { -// log.Fatal("Error registering artifact:", err) -// } -// fmt.Println("Artifact registered successfully") -// -// // Retrieve an Artifact -// artifact, err := artifactsAPI.GetArtifact("example-subject", "latest") -// if err != nil { -// log.Fatal("Error fetching artifact:", err) -// } -// fmt.Println("Retrieved artifact:", artifact) +// // Initialize the API client +// config := client.Config{ +// BaseURL: "https://my-registry.example.com", +// AuthToken: "my-token", +// } +// apiClient := client.NewApicurioClient(config) +// +// // Access the ArtifactsAPI +// artifactsAPI := apis.NewArtifactsAPI(apiClient) +// +// // Create a new artifact +// artifact := models.Artifact{ +// GroupID: "example-group", +// ID: "example-artifact", +// Content: []byte(`{"type": "record", "name": "Example", "fields": [{"name": "field1", "type": "string"}]}`), +// ContentType: "application/json", +// } +// response, err := artifactsAPI.Create(artifact) +// if err != nil { +// fmt.Printf("Error creating artifact: %v\n", err) +// return +// } +// fmt.Printf("Artifact created with ID: %s\n", response.ID) +// +// // Retrieve artifact metadata +// metadata, err := artifactsAPI.GetMetadata("example-group", "example-artifact") +// if err != nil { +// fmt.Printf("Error retrieving metadata: %v\n", err) +// return +// } +// fmt.Printf("Artifact metadata: %+v\n", metadata) // } +// +// Note: +// +// Each API can be accessed via its respective constructor function (e.g., `NewArtifactsAPI`, +// `NewAdminAPI`). These APIs are designed to integrate seamlessly with the client package. package apis diff --git a/client/doc.go b/client/doc.go index 1d334d2..c8861a0 100644 --- a/client/doc.go +++ b/client/doc.go @@ -1,7 +1,63 @@ -// Package client provides the core functionality to interact with -// the Apicurio Registry. It includes methods to retrieve, register, -// and validate schemas. +// Package client provides the core client implementation for interacting with the Apicurio Registry. // -// This package is the backbone of the library, and developers -// typically start with the `NewApicurioClient` function. +// The client package is the entry point for initializing and configuring the Apicurio Registry client. +// It abstracts the complexities of making HTTP requests to the registry and provides a clean interface +// for developers to use in their applications. +// +// Features: +// +// - Centralized configuration for base URL and authentication. +// - Automatic retry mechanisms for transient failures. +// - Thread-safe implementation suitable for concurrent use. +// - Extensible architecture to support additional features and middleware. +// +// Usage: +// +// To use the client, create a new instance using the `NewApicurioClient` function and pass a `Config` structure +// with the required settings such as BaseURL and AuthToken. +// +// Example: +// +// package main +// +// import ( +// "fmt" +// "github.com/mollie/go-apicurio-registry/client" +// ) +// +// func main() { +// // Define the client configuration +// config := client.Config{ +// BaseURL: "https://my-registry.example.com", +// AuthToken: "my-token", +// } +// +// // Initialize the client +// apiClient := client.NewApicurioClient(config) +// +// // Check the connection to the registry +// status, err := apiClient.CheckConnection() +// if err != nil { +// fmt.Printf("Error connecting to the registry: %v\n", err) +// return +// } +// fmt.Printf("Registry status: %v\n", status) +// } +// +// Configuration: +// +// The `Config` struct contains the following fields: +// - BaseURL: The URL of the Apicurio Registry. +// - AuthToken: A token used for authenticating requests. +// - HTTPClient: (Optional) A custom HTTP client for advanced use cases. +// +// Methods: +// +// The client provides several methods to interact with the registry, including: +// - `CheckConnection`: Verifies if the registry is reachable. +// - `DoRequest`: Executes raw HTTP requests for advanced use cases. +// +// Thread Safety: +// +// The client is designed to be thread-safe and can be used in concurrent environments without additional synchronization. package client diff --git a/doc.go b/doc.go index fe55321..cb0b397 100644 --- a/doc.go +++ b/doc.go @@ -1,21 +1,68 @@ -// Package apicurio provides a client library for interacting with the Apicurio Registry. -// It allows developers to manage schemas, validate payloads, and perform schema evolution. +// Package apicurio provides a Go client library for interacting with the Apicurio Registry. +// +// The library enables developers to seamlessly integrate with the Apicurio Registry +// for managing, evolving, and validating schemas in a variety of serialization formats. // // Features: -// - CRUD operations on schemas. -// - Schema validation and compatibility checks. -// - Support for multiple serialization formats like Avro, Protobuf, and JSON Schema. // -// Example usage: +// - CRUD operations on schemas (artifacts) including creation, retrieval, update, and deletion. +// - Management of schema versions, branches, and metadata. +// - Group-based organization for schemas to support multi-tenancy. +// - Schema validation and compatibility checks for supported formats such as Avro, Protobuf, and JSON Schema. +// - System-level operations such as retrieving registry status and configuration. +// +// Structure: +// +// The library is structured into the following key components: +// +// 1. **Client**: Provides an entry point for interacting with the registry. +// Use the `client.NewApicurioClient` function to create a new client instance. +// +// 2. **APIs**: Contains modular functions for specific operations such as managing artifacts, +// branches, versions, groups, and performing administrative tasks. +// +// 3. **Models**: Defines data structures for requests, responses, and errors used across the library. // -// import "github.com/mollie/go-apicurio-registry/client" +// Example Usage: +// +// The following example demonstrates how to create a new artifact and retrieve its metadata: +// +// package main +// +// import ( +// "fmt" +// "github.com/mollie/go-apicurio-registry/client" +// "github.com/mollie/go-apicurio-registry/models" +// ) // // func main() { -// client := client.NewApicurioClient("https://registry.example.com") -// schema, err := client.GetSchema("example-subject", "latest") -// if err != nil { -// log.Fatal(err) -// } -// fmt.Println("Schema:", schema) +// // Initialize the client +// config := client.Config{ +// BaseURL: "https://my-registry.example.com", +// AuthToken: "my-token", +// } +// apiClient := client.NewApicurioClient(config) +// +// // Create a new artifact +// artifact := models.Artifact{ +// GroupID: "example-group", +// ID: "example-artifact", +// Content: []byte(`{"type": "record", "name": "Example", "fields": [{"name": "field1", "type": "string"}]}`), +// ContentType: "application/json", +// } +// response, err := apiClient.Artifacts.Create(artifact) +// if err != nil { +// fmt.Printf("Error creating artifact: %v\n", err) +// return +// } +// fmt.Printf("Artifact created with ID: %s\n", response.ID) +// +// // Retrieve artifact metadata +// metadata, err := apiClient.Artifacts.GetMetadata("example-group", "example-artifact") +// if err != nil { +// fmt.Printf("Error retrieving metadata: %v\n", err) +// return +// } +// fmt.Printf("Artifact metadata: %+v\n", metadata) // } package apicurio diff --git a/models/docs.go b/models/doc.go similarity index 100% rename from models/docs.go rename to models/doc.go