[
https://issues.apache.org/jira/browse/FLINK-39359?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=18070291#comment-18070291
]
Rui Fan commented on FLINK-39359:
---------------------------------
FYI, following is the analysis from Claude:
Currently, there is no CI check to verify that the generated REST API
documentation files ({{{}rest_v1_dispatcher.html{}}},
{{{}rest_v1_dispatcher.yml{}}}, etc.) stay in sync with the code.
What exists today:
* *{{RuntimeRestAPIStabilityTest}}* (in {{{}flink-runtime-web{}}}) — compares
a committed {{rest_api_v1.snapshot}} against the current code to detect
*backward-incompatible REST API changes* (removed endpoints, changed types,
etc.). This is a compatibility/stability guard, not a documentation freshness
check.
* *{{ConfigOptionsDocsCompletenessITCase}}* (in {{{}flink-docs{}}}) — verifies
that all {{ConfigOption}} definitions have corresponding entries in the
generated HTML docs. This is the pattern we could follow for REST API docs.
* *Manual generation* — developers must run {{./mvnw package
-Dgenerate-rest-docs -pl flink-docs -am -nsu -DskipTests}} and commit the
output. There is no CI step that validates whether the committed files match
what the generator would produce.
A possible approach: add an IT case (similar to
{{{}ConfigOptionsDocsCompletenessITCase{}}}) that regenerates the REST API docs
in a temp directory and diffs them against the committed files, failing if they
diverge.
> Introduce a mechanism to ensure that the generated documentation stays
> consistent with the code.
> ------------------------------------------------------------------------------------------------
>
> Key: FLINK-39359
> URL: https://issues.apache.org/jira/browse/FLINK-39359
> Project: Flink
> Issue Type: Improvement
> Components: Build System
> Reporter: Yuepeng Pan
> Priority: Major
>
> TO prevent the issue like https://issues.apache.org/jira/browse/FLINK-39041
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
