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

This commit 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.

chore: apply feedback

chore: fix heading to use title casing

chore: add . after sentences

chore: apply feedback

Author: youngjungithub

website/docs/reference/openapi-generator/cli.md

@@ -0,0 +1,53 @@
+---
+sidebar_position: 2
+---
+
+# Command-line Interface
+
+## Overview
+
+The `openapi-generator` CLI tool converts your `@api-ts/io-ts-http` `apiSpec` definition
+into an OpenAPI 3.0 specification. When you run this tool, it reads a TypeScript file
+containing your API definition and outputs the OpenAPI specification to stdout.
+
+## Usage Syntax
+
+```shell
+openapi-generator [OPTIONS] [FLAGS] <file>
+```
+
+## Arguments
+
+- `<file>`: (Required) Path to the TypeScript file containing the exported `apiSpec`
+  definition.
+
+## Options
+
+- `--name`, `-n <string>`: Specifies the API name in the generated specification.
+- `--version`, `-v <string>`: Specifies the API version in the generated OpenAPI
+  specification. If an `@version` JSDoc tag is present on the `apiSpec` export, that
+  value takes precedence.
+- `--codec-file`, `-c <string>`: Path to a JavaScript configuration file defining
+  schemas for custom or external io-ts codecs. See
+  [Defining custom codec schemas](./configuration#defining-custom-codec-schemas) for
+  details.
+
+## Flags
+
+- `--internal`, `-i`: Includes routes marked with the `@private` JSDoc tag in the
+  generated output. By default, private routes are excluded.
+- `--help`, `-h`: Displays the help message describing arguments, options, and flags.
+
+## Examples
+
+You can generate an OpenAPI specification and save it to a file:
+
+```shell
+npx openapi-generator src/index.ts > openapi-spec.json
+```
+
+You can specify API name, version, and custom codec definitions:
+
+```shell
+npx openapi-generator --name "My Service API" --version "2.1.0" --codec-file ./custom-codecs.js src/api.ts
+```

website/docs/reference/openapi-generator/configuration.md

@@ -0,0 +1,142 @@
+---
+sidebar_position: 3
+---
+
+# Configuration
+
+## Overview
+
+You need to configure the generator to:
+
+- Correctly interpret `io-ts` types from external packages.
+- Define OpenAPI schemas for custom `io-ts` codecs that can't be automatically derived
+  from the Abstract Syntax Tree (AST).
+
+## Preparing External Types Packages
+
+To process `io-ts` types imported from other npm packages, ensure the following in the
+external package's `package.json`:
+
+1. Include source code in the published npm bundle by adding the source directory to the
+   `files` array:
+
+   ```json
+   // package.json of the external types package
+   {
+     "name": "my-external-types",
+     "version": "1.0.0",
+     "files": [
+       "dist/",
+       "src/" // Include source code
+     ],
+     "main": "dist/index.js",
+     "types": "dist/index.d.ts",
+     "source": "src/index.ts" // Add this field
+     // ... rest of package.json
+   }
+   ```
+
+2. Specify the source entry point using the `source` field (for example,
+   `"source": "src/index.ts"`).
+
+## Defining Custom Codec Schemas
+
+For custom `io-ts` codecs (such as those using `new t.Type(...)` or complex types not
+directly supported), you must define schemas manually using one of these methods:
+
+### Method 1: Via `openapi-gen.config.js` (Recommended For Type Authors)
+
+You can define schemas directly within the package that declares the custom codecs:
+
+1. Create a file named `openapi-gen.config.js` in the root of the types package.
+
+2. Update the package's `package.json` to include:
+
+- The `customCodecFile` field pointing to this file.
+- The config file in the `files` array.
+
+  ```json
+  // package.json of the types package defining custom codecs
+  {
+    "name": "my-custom-codec-package",
+    // ...
+    "files": [
+      "dist/",
+      "src/",
+      "openapi-gen.config.js" // Include the config file
+    ],
+    "customCodecFile": "openapi-gen.config.js" // Point to the file
+    // ...
+  }
+  ```
+
+3. Structure the `openapi-gen.config.js` file as follows:
+
+   ```javascript
+   // openapi-gen.config.js
+   module.exports = (E) => {
+     return {
+       // Key matches the exported codec name (e.g., export const MyCustomString = ...)
+       MyCustomString: () =>
+         E.right({
+           type: 'string',
+           format: 'custom-format',
+           description: 'A custom string type definition',
+         }),
+       AnotherCustomType: () =>
+         E.right({
+           type: 'object',
+           properties: {
+             /* ... */
+           },
+         }),
+       // ... other custom codec definitions
+     };
+   };
+   ```
+
+The exported function receives the `fp-ts/Either` namespace (`E`) as an argument. You
+should return an object where:
+
+- Keys are the exported names of your custom codecs.
+- Values are functions that return `E.right()` with an OpenAPI schema object.
+
+### Method 2: Via `--codec-file` Option (For Consumers)
+
+You can define schemas in a configuration file within your project and pass the file
+path via the `--codec-file` option:
+
+1. Create a JavaScript file (for example, `custom-codecs.js`).
+
+2. Structure the file similarly to Method 1, but group definitions by package:
+
+   ```javascript
+   // custom-codecs.js
+   module.exports = (E) => {
+     return {
+       'io-ts-bigint': {
+         // Package name
+         BigIntFromString: () => E.right({ type: 'string', format: 'bigint' }),
+         NonZeroBigIntFromString: () =>
+           E.right({ type: 'string', format: 'bigint' /* constraints */ }),
+         // ... other codecs from 'io-ts-bigint'
+       },
+       'my-other-custom-package': {
+         // Another package
+         SomeType: () => E.right({ type: 'number', format: 'float' }),
+       },
+       // ... other packages
+     };
+   };
+   ```
+
+In this structure:
+
+- Keys of the top-level object are package names.
+- Values are objects that map codec names to their schema definitions.
+
+3. Run the generator with the `--codec-file` option:
+
+   ```shell
+   npx openapi-generator --codec-file ./custom-codecs.js src/index.ts
+   ```

website/docs/reference/openapi-generator/index.md

@@ -0,0 +1,16 @@
+---
+sidebar_position: 1
+---
+
+# OpenAPI Generator
+
+This section provides technical reference for the `@api-ts/openapi-generator`
+command-line utility. The documentation covers:
+
+- CLI usage and options.
+- Configuration settings.
+- Supported `io-ts` primitives.
+- JSDoc annotation system.
+
+You can use this reference to generate OpenAPI 3.0 specifications from your
+`@api-ts/io-ts-http` API definitions.