docs(openapi-generator): Refactor documentation to Diátaxis Reference format

[youngjungithub]

This PR significantly refactors the documentation for the @api-ts/openapi-generator package to align with the Reference section principles of the Diátaxis framework. The goal is to provide users with a clear, structured, and authoritative technical description suitable for direct consultation during development.

Key Changes:

• Restructured the entire README.md into a dedicated Reference section, replacing the previous narrative format.
• Organized content into logical subsections for improved navigability and focus:
  • Command-Line Interface (CLI): Provides a technical overview, usage syntax, and detailed descriptions of the <file> argument, options (--name, --version, --codec-file), and flags (--internal, --help), along with concrete usage examples.
  • Configuration: Clearly documents the requirements for preparing external types packages (specifying files and source in the external package's package.json). Details the two distinct methods for defining custom codec schemas:
    1. Via openapi-gen.config.js within the types package (recommended for type authors), including file naming, package.json requirements (customCodecFile, files), and file structure.
    2. Via the --codec-file CLI option for consumers, specifying the required file structure (grouping by package name).
  • Supported io-ts Primitives: Includes a definitive list of io-ts primitives and combinators that the generator can automatically interpret to produce OpenAPI schemas.
  • JSDoc Annotations: Exhaustively documents the supported JSDoc tags used to enrich the generated OpenAPI specification, categorized by:
    • Endpoint Annotations (applied to httpRoute variables): Covers Summary, Description, @operationId, @tag, @private, @unstable, @example, and the handling of unknown tags (x-unknown-tags), explaining their direct mapping to OpenAPI Operation Object fields (like summary, description, operationId, tags, x-internal, x-unstable, example, x-unknown-tags).
    • Schema Annotations (applied to io-ts types/fields): Details how to add descriptions via JSDoc text and lists all supported standard OpenAPI tags (@default, @example, @minLength, @maximum, @pattern, @format, etc.) and custom tags (@private, @deprecated), explaining their effect on the resulting OpenAPI Schema Object or Property (like description, default, minLength, deprecated, x-internal). Includes comprehensive examples demonstrating tag usage.
• Removed introductory explanations and narrative prose, focusing strictly on factual, technical descriptions of the tool's features, configuration requirements, and behavior based on inputs (like JSDoc tags).

Impact:

This restructuring provides developers using @api-ts/openapi-generator with significantly improved technical reference documentation. The information is now presented in a consistent, predictable, and easily searchable format, adhering to the Diátaxis framework's guidelines for effective reference material. This makes it easier for users to find the specific technical details they need regarding CLI usage, configuration, supported types, and JSDoc annotation capabilities while working with the generator.