Publish ToolHive Operator CRD Spec

[ChrisJBurns]

TL;DR

We need to publish our Custom Resource Definition (CRD) specification with comprehensive field documentation so users can understand available configuration options and expected values before deploying our operator. How we do this is the purpose of this ticket. We ideally want something automatic and not too involved.

Problem

Users currently have no way to discover what fields are available in our CRDs, what values are expected, or how to properly configure custom resources. This creates a poor developer experience where users must either:

• Guess at configuration options
• Dig through source code to understand the API
• Install the operator blindly without understanding its capabilities

Proposed Solution

Publish well-documented CRD specifications that include:

1. Annotated CRD YAML with comprehensive field descriptions using OpenAPI schema annotations

2. API Reference Documentation generated from the CRD schemas showing:

   • All available fields and their types
   • Required vs optional fields
   • Default values and validation rules
   • Field descriptions and usage examples

3. Example Custom Resources demonstrating common configuration patterns

Implementation Options

• GitHub Pages/Docs Site: Host generated API documentation
• README/Wiki: Include CRD field reference in repository documentation
• Schema Registry: Publish to a schema registry with browseable interface
• OpenAPI Spec: Generate and publish OpenAPI specifications from CRDs

Acceptance Criteria

• CRD schemas include detailed field descriptions and validation rules
• Users can browse available fields and their purposes without installing the operator
• Documentation includes examples showing how to use different field combinations
• Field descriptions explain expected values, formats, and constraints
• Documentation is automatically updated when CRD schemas change
• Users can validate their custom resources against published schemas

Additional Considerations

Use clear, user-friendly descriptions rather than technical implementation details
Include troubleshooting guidance for common configuration mistakes
Provide migration guides when CRD versions change
Consider interactive documentation tools for better user experience