You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@flink.apache.org by "Rui Fan (Jira)" <ji...@apache.org> on 2026/04/01 10:26:00 UTC
[jira] [Commented] (FLINK-39359) Introduce a mechanism to ensure that the generated documentation stays consistent with the code.
[ 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)