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
youngjungithub
force-pushed
the
docs/refactor-openapi-generator-docs
branch
2 times, most recently
from
035255a to
8046350
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
chore: add . after sentences
chore: apply feedback
youngjungithub
force-pushed
the
docs/refactor-openapi-generator-docs
branch
from
65ce5d0 to
a0399b6
Compare
vmccarty
approved these changes
Apr 23, 2025
|
🎉 This PR is included in version @api-ts/typed-express-router@2.0.0-beta.1 🎉 The release is available on npm package (@beta dist-tag) Your semantic-release bot 📦🚀 |
|
🎉 This PR is included in version @api-ts/express-wrapper@2.0.0-beta.1 🎉 The release is available on npm package (@beta dist-tag) Your semantic-release bot 📦🚀 |
|
🎉 This PR is included in version @api-ts/typed-express-router@1.1.14 🎉 The release is available on npm package (@latest dist-tag) Your semantic-release bot 📦🚀 |
|
🎉 This PR is included in version @api-ts/express-wrapper@1.0.34 🎉 The release is available on npm package (@latest dist-tag) Your semantic-release bot 📦🚀 |
|
🎉 This PR is included in version @api-ts/superagent-wrapper@1.3.4 🎉 The release is available on npm package (@latest dist-tag) Your semantic-release bot 📦🚀 |
|
🎉 This PR is included in version @api-ts/openapi-generator@5.8.0 🎉 The release is available on npm package (@latest dist-tag) Your semantic-release bot 📦🚀 |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
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.