chore: apply feedback

youngjungithub · youngjungithub · commit eaf77a0c6a1c · 2025-04-21T15:17:04.000-04:00
diff --git a/website/docs/reference/openapi-generator/cli.md b/website/docs/reference/openapi-generator/cli.md
@@ -7,8 +7,8 @@ sidebar_position: 2
 ## Overview
 
 The `openapi-generator` CLI tool converts your `@api-ts/io-ts-http` `apiSpec` definition
-into an OpenAPI specification document. When you run this tool, it reads a TypeScript
-file containing your API definition and outputs the OpenAPI specification to stdout.
+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
 
@@ -23,8 +23,7 @@ openapi-generator [OPTIONS] [FLAGS] <file>
 
 ## Options
 
-- `--name`, `-n <string>`: Specifies the API name in the generated OpenAPI
-  specification.
+- `--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.
diff --git a/website/docs/reference/openapi-generator/configuration.md b/website/docs/reference/openapi-generator/configuration.md
@@ -8,9 +8,9 @@ sidebar_position: 3
 
 You need to configure the generator to:
 
-- Correctly interpret `io-ts` types from external packages
+- 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)
+  from the Abstract Syntax Tree (AST).
 
 ## Preparing external types packages
 
@@ -20,21 +20,21 @@ 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
-}
-```
+   ```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"`)
@@ -51,48 +51,49 @@ You can define schemas directly within the package that declares the custom code
 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
-  // ...
-}
-```
+
+- 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
-  };
-};
-```
+   ```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:
@@ -109,25 +110,25 @@ path via the `--codec-file` option:
 
 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
-  };
-};
-```
+   ```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:
 
@@ -136,6 +137,6 @@ In this structure:
 
 3. Run the generator with the `--codec-file` option:
 
-```shell
-npx openapi-generator --codec-file ./custom-codecs.js src/index.ts
-```
+   ```shell
+   npx openapi-generator --codec-file ./custom-codecs.js src/index.ts
+   ```
diff --git a/website/docs/reference/openapi-generator/jsdoc.md b/website/docs/reference/openapi-generator/jsdoc.md
@@ -4,7 +4,7 @@ You can use JSDoc comments to enrich the generated OpenAPI specification. This r
 describes the supported annotations for both endpoint definitions and schema
 definitions.
 
-## Endpoint annotations
+## Endpoint Annotations
 
 You can add JSDoc comments to variables holding `h.httpRoute` definitions to provide
 metadata for the corresponding OpenAPI operation object.
@@ -158,12 +158,12 @@ const UserProfile = t.type({
 });
 ```
 
-### Supported OpenAPI tags
+### Supported OpenAPI Tags
 
 You can use the following JSDoc tags, which map directly to standard OpenAPI schema
 keywords:
 
-| JSDoc tag                 | OpenAPI property   | Description                        |
+| JSDoc Tag                 | OpenAPI Property   | Description                        |
 | ------------------------- | ------------------ | ---------------------------------- |
 | `@default <value>`        | `default`          | Default value                      |
 | `@example <value>`        | `example`          | Example value                      |
@@ -185,9 +185,9 @@ keywords:
 | `@format <format>`        | `format`           | Format (e.g., `uuid`, `date-time`) |
 | `@title <title>`          | `title`            | Schema title                       |
 
-### Custom tags
+### Custom Tags
 
-| JSDoc tag     | OpenAPI property   | Description                      |
+| JSDoc Tag     | OpenAPI Property   | Description                      |
 | ------------- | ------------------ | -------------------------------- |
 | `@private`    | `x-internal: true` | Marks schema/field as internal   |
 | `@deprecated` | `deprecated: true` | Marks schema/field as deprecated |
