docs(openapi-generator): Refactor documentation to Diátaxis Reference format #1038
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
youngjungithub
force-pushed
the
docs/refactor-openapi-generator-docs
branch
from
e0fbf18 to
34b3ce2
Compare
vmccarty
reviewed
Apr 21, 2025
| ## 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 |
There was a problem hiding this comment.
Suggested change
| into an OpenAPI specification document. When you run this tool, it reads a TypeScript | |
| into an OpenAPI 3.0 specification. When you run this tool, it reads a TypeScript |
Comment on lines
26
to
27
| - `--name`, `-n <string>`: Specifies the API name in the generated OpenAPI | ||
| specification. |
There was a problem hiding this comment.
Suggested change
| - `--name`, `-n <string>`: Specifies the API name in the generated OpenAPI | |
| specification. | |
| - `--name`, `-n <string>`: Specifies the API name in the generated specification. |
You've already introduced the term OpenAPI 3.0 specification, so no need to say the full name every time. From this point forward on this page, simply use specification.
|
|
||
| You need to configure the generator to: | ||
|
|
||
| - Correctly interpret `io-ts` types from external packages |
There was a problem hiding this comment.
Suggested change
| - Correctly interpret `io-ts` types from external packages | |
| - Correctly interpret `io-ts` types from external packages. |
Bullet points that form complete sentences should get periods.
| 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 |
There was a problem hiding this comment.
Suggested change
| - Define OpenAPI schemas for custom `io-ts` codecs that can't be automatically derived | |
| - Define OpenAPI schemas for custom `io-ts` codecs that can't be automatically derived. |
Comment on lines
23
to
37
| ```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 | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Indent this so it aligns with the numbering. I think 1 or 2 tabs.
| describes the supported annotations for both endpoint definitions and schema | ||
| definitions. | ||
|
|
||
| ## Endpoint annotations |
There was a problem hiding this comment.
Suggested change
| ## Endpoint annotations | |
| ## Endpoint Annotations |
| }); | ||
| ``` | ||
|
|
||
| ### Supported OpenAPI tags |
There was a problem hiding this comment.
Suggested change
| ### 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 | |
There was a problem hiding this comment.
Suggested change
| | JSDoc tag | OpenAPI property | Description | | |
| | JSDoc Tag | OpenAPI Property | Description | |
| | `@format <format>` | `format` | Format (e.g., `uuid`, `date-time`) | | ||
| | `@title <title>` | `title` | Schema title | | ||
|
|
||
| ### Custom tags |
There was a problem hiding this comment.
Suggested change
| ### Custom tags | |
| ### Custom Tags |
|
|
||
| ### Custom tags | ||
|
|
||
| | JSDoc tag | OpenAPI property | Description | |
There was a problem hiding this comment.
Suggested change
| | JSDoc tag | OpenAPI property | Description | | |
| | JSDoc Tag | OpenAPI Property | Description | |
youngjungithub
force-pushed
the
docs/refactor-openapi-generator-docs
branch
from
eaf77a0 to
38b5681
Compare
… 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
youngjungithub
force-pushed
the
docs/refactor-openapi-generator-docs
branch
from
035255a to
8046350
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR significantly refactors the documentation for the
@api-ts/openapi-generatorpackage 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:
<file>argument, options (--name,--version,--codec-file), and flags (--internal,--help), along with concrete usage examples.filesandsourcein the external package'spackage.json). Details the two distinct methods for defining custom codec schemas:openapi-gen.config.jswithin the types package (recommended for type authors), including file naming,package.jsonrequirements (customCodecFile,files), and file structure.--codec-fileCLI option for consumers, specifying the required file structure (grouping by package name).io-tsPrimitives: Includes a definitive list ofio-tsprimitives and combinators that the generator can automatically interpret to produce OpenAPI schemas.httpRoutevariables): 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 (likesummary,description,operationId,tags,x-internal,x-unstable,example,x-unknown-tags).io-tstypes/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 (likedescription,default,minLength,deprecated,x-internal). Includes comprehensive examples demonstrating tag usage.Impact:
This restructuring provides developers using
@api-ts/openapi-generatorwith 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.