fix: Update shadow-api-detector for OpenAPI 3.2 compatibility and plugin use - #97
Closed
Arc-E-Tect wants to merge 6 commits into
Closed
fix: Update shadow-api-detector for OpenAPI 3.2 compatibility and plugin use#97Arc-E-Tect wants to merge 6 commits into
Arc-E-Tect wants to merge 6 commits into
Conversation
What changed: - Upgraded swagger parser dependency from 2.1.45 to 2.1.46 in the shadow-api-detector version catalog. - Updated OpenApiEndpointCollector to parse via OpenAPIV3Parser and added an explicit OpenAPI 3.2 compatibility path. - Added compatibility logic that, on failed parse of a root document declaring openapi: 3.2.x, creates a temporary root document in the same directory with only the version rewritten to 3.1.0, parses that file, and then deletes it. - Added OpenApiEndpointCollector tests and fixtures for OpenAPI 3.2 single-file and multi-file (relative ) scenarios. - Added a new runnable example project at examples/shadow-api-detector/openapi-3-2 demonstrating successful detectShadowApis execution with openapi: 3.2.0. - Added a dedicated workflow example-shadow-api-detector-openapi-3-2-build.yml to validate the new example in CI. - Updated examples/README.adoc to include the new OpenAPI 3.2 example README. - Expanded shadow-api-detector/README.adoc compatibility docs with explicit limitations and a clear explanation that current OpenAPI 3.2 support is implemented via a temporary 3.1 compatibility document workaround. Why this was needed: - OpenAPI 3.2 documents previously failed to parse with the current parser stack, even though endpoint extraction logic only requires successful path/operation parsing. - The plugin needed a practical compatibility mechanism to support existing 3.2 contracts while preserving behavior for already-supported 3.0/3.1 inputs. - The repository required a dedicated, documented example and CI coverage for this compatibility path. How it works: - Normal parse is attempted first. - If parse fails and the root explicitly declares 3.2.x, the plugin writes a temporary sibling root file, rewrites only the root openapi version token to 3.1.0, parses the temporary file so relative refs remain valid, and then removes the temporary file. - Endpoint collection and report behavior remain unchanged after parsing succeeds. Side effects, constraints, and caveats: - This is an explicit compatibility workaround, not native end-to-end OpenAPI 3.2 parser support. - OpenAPI v2 remains unsupported. - OpenAPI versions newer than 3.2 remain unsupported. Validation and outcomes: - shadow-api-detector test suite passes after the change. - The new openapi-3-2 example runs detectShadowApis successfully and reports 0 shadow endpoints for the sample controller. - actionlint passes for the new example workflow.
…compatibility section of README
…tibility mode What changed: - Added collection metadata in OpenApiEndpointCollector to indicate whether OpenAPI 3.2 compatibility mode was used during parsing. - Updated DetectShadowApisTask to use collector metadata and pass a compatibility flag into report generation. - Extended ShadowApiReportWriter with a boolean-aware write overload that emits a WARNING disclaimer block when the OpenAPI 3.2 workaround path was used. - Added/updated tests to verify disclaimer behavior at both report-writer and task levels. Why this was needed: - The generated report previously did not indicate that OpenAPI 3.2 parsing was performed via a temporary 3.1 compatibility document workaround. - Users need explicit in-report transparency so results are interpreted with the correct compatibility context. How it works: - The collector now returns endpoints plus a usedOpenApi32CompatibilityWorkaround flag. - The task propagates that flag to the report writer. - The writer conditionally adds an AsciiDoc WARNING block describing that 3.2 parsing used a temporary root compatibility copy rewritten to 3.1.0. Side effects and caveats: - Report content changes only when the compatibility workaround path is actually used. - Endpoint detection logic and failOnShadow behavior remain unchanged. Validation and outcomes: - shadow-api-detector test suite passes, including new disclaimer assertions.
…n to 0.4.0 What changed:\n- Updated examples/shadow-api-detector/with-shadow-apis/gradle/libs.versions.toml\n- Changed the shadow-api-detector version reference from 0.3.0 to 0.4.0\n\nWhy:\n- The example should consume the latest released plugin behavior used elsewhere in this update set\n- Keeping the example on 0.3.0 could hide newer report behavior and create inconsistent results between examples\n\nHow:\n- The version alias in the example's version catalog was advanced to 0.4.0\n- No task wiring or runtime semantics were changed beyond selecting the newer plugin artifact\n\nConstraints and caveats:\n- This commit intentionally updates only the with-shadow-apis example catalog to keep the change isolated\n\nOutcome:\n- The remaining dirty file is committed as its own logical unit, separate from the OpenAPI 3.2 disclaimer code changes.
…ss examples What changed:\n- Removed local composite-build plugin wiring from examples/shadow-api-detector/openapi-3-2/settings.gradle\n- Updated shadow-api-detector plugin version to 0.4.0 in:\n - examples/shadow-api-detector/clean/gradle/libs.versions.toml\n - examples/shadow-api-detector/multi-file-openapi/gradle/libs.versions.toml\n - examples/shadow-api-detector/openapi-3-2/gradle/libs.versions.toml\n- Updated examples/shadow-api-detector/openapi-3-2/README.adoc to document that it uses the official published plugin release\n\nWhy:\n- Examples should validate the public plugin as consumers use it, not local uncommitted source code\n- Local includeBuild wiring can mask publication-state differences and make behavior appear available before release\n\nHow:\n- Switched the OpenAPI 3.2 example from includeBuild-based plugin resolution to Gradle Plugin Portal resolution\n- Standardized shadow-api-detector example version catalogs on 0.4.0 for consistent behavior across examples\n\nSide effects and constraints:\n- Example behavior now reflects published plugin capabilities only\n- Future feature verification in examples requires released plugin versions unless local wiring is intentionally reintroduced\n\nOutcome:\n- OpenAPI 3.2 example continues to run successfully with ./gradlew clean detectShadowApis using published artifacts.
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
Summary
This pull request introduces the following changes:
Add OpenAPI 3.2 Compatibility Support:
Standardize Plugin Version in Examples:
0.4.0across all examples to use the latest published release.includeBuildplugin dependencies to enforce validation with published artifacts.Enhance Report Transparency:
Documentation Improvements: