Enhance documentation to support OpenAPI 3.0-3.2 features and clarify usage instructions

[shibayan]

This pull request updates the documentation to highlight and clarify support for OpenAPI 3.2, improve guidance on MSBuild integration, and document new features such as enhanced error handling, XML documentation generation, and support for nullable type arrays. The changes span the main README and all English and Japanese documentation, ensuring consistency and clearer instructions for users.

Major documentation updates:

OpenAPI 3.2 and Schema Support:

• All references to supported OpenAPI versions are updated to "OpenAPI 3.0-3.2" throughout the documentation, including in feature lists, schema mapping, and prerequisites. [1] [2] [3] [4] [5] [6] [7] [8] [9]
• Detailed documentation is added for OpenAPI 3.2 features, especially support for nullable type arrays (type: ["string", "null"]), including C# mapping examples. [1] [2] [3]

MSBuild Integration and Document Discovery:

• Guidance is added to use OpenApiWeaverDocument instead of AdditionalFiles, with explanations of how MSBuild targets project these items and their metadata into the source generator. [1] [2] [3]
• New sections clarify that only OpenApiWeaverDocument items are processed, and how metadata like ClientName and Namespace are handled. [1] [2]

Enhanced Feature Documentation:

• Expanded documentation of runtime error handling, including the use of OpenApiException and OpenApiException<TError>, error schema matching, and example usage. [1] [2]
• Improved explanation of XML documentation generation, showing how summaries, descriptions, and tag metadata are used for IntelliSense, and that HTML is stripped. [1] [2] [3]
• Clarified response handling (preference for JSON, handling of empty bodies), request body format selection, and fallback strategies for schema mapping. [1] [2]

Process and How-It-Works:

• The "How it works" section is expanded to include MSBuild projection, OpenAPI 3.2 parsing, HTML sanitization for docs, and explicit error handling in generated clients. [1] [2]

Japanese Documentation:

• All above improvements are mirrored in the Japanese docs for consistency. [1] [2] [3] [4]

These updates make the documentation more accurate, user-friendly, and reflective of the latest capabilities of OpenApiWeaver.

[Copilot]

Pull request overview

Documentation-focused PR to align OpenApiWeaver docs with newly supported OpenAPI 3.2 capabilities and to clarify MSBuild-based document discovery/configuration across both English and Japanese docs.

Changes:

• Update stated supported OpenAPI version range to OpenAPI 3.0–3.2 across README and docs.
• Add/expand documentation for nullable type arrays, runtime error handling (OpenApiException), and XML doc generation details.
• Clarify MSBuild integration: OpenApiWeaverDocument usage, projection into AdditionalFiles, and metadata flow (ClientName, Namespace).

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
README.md	Updates headline feature/support messaging and adds MSBuild guidance note.
docs/en/index.md	Updates landing page tagline and feature blurb to 3.0–3.2.
docs/en/getting-started.md	Updates prerequisites and clarifies document inclusion guidance.
docs/en/configuration.md	Expands MSBuild projection and document discovery documentation.
docs/en/features.md	Updates version messaging and adds runtime error handling / XML docs sections.
docs/en/schema-types.md	Adds nullable type array documentation and mapping example.
docs/ja/index.md	Mirrors landing page tagline and feature blurb updates in Japanese.
docs/ja/getting-started.md	Mirrors prerequisites and inclusion guidance updates in Japanese.
docs/ja/configuration.md	Mirrors MSBuild projection and discovery documentation in Japanese.
docs/ja/features.md	Mirrors features expansion (error handling, XML docs, 3.2 notes) in Japanese.
docs/ja/schema-types.md	Mirrors nullable type array documentation and mapping example in Japanese.
docs/en/how-it-works.md	Expands the pipeline description (MSBuild projection, docs sanitization, error handling).
docs/ja/how-it-works.md	Mirrors the expanded “How it works” pipeline description in Japanese.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.