[FLINK-39359][docs] Introduce integration test cases to ensure that the generated REST-API related documentation stays consistent with the code. by RocMarshal · Pull Request #27884 · apache/flink

RocMarshal · 2026-04-02T06:55:09Z

What is the purpose of the change

[FLINK-39359][docs] Introduce integration test cases to ensure that the generated REST-API related documentation stays consistent with the code.

Brief change log

Introduced :

RuntimeOpenRestAPIDocsCompletenessITCase
SqlGatewayOpenRestAPIDocsCompletenessITCase
Why introduce two cases classes for this issue?

Given the static nature and shared context of OpenApiSpecGenerator#modelConverterContext, placing all test methods in a single class would lead to unnecessary pollution of the generated files. Therefore, splitting them into two separate files to isolate the static scope of OpenApiSpecGenerator#modelConverterContext is a clean implementation approach.

Verifying this change

This change is already covered by existing tests, such as (please describe tests).

Does this pull request potentially affect one of the following parts:

Dependencies (does it add or upgrade a dependency): (yes / no)
The public API, i.e., is any changed class annotated with @Public(Evolving): (yes / no)
The serializers: (yes / no / don't know)
The runtime per-record code paths (performance sensitive): (yes / no / don't know)
Anything that affects deployment or recovery: JobManager (and its components), Checkpointing, Kubernetes/Yarn, ZooKeeper: (yes / no / don't know)
The S3 file system connector: (yes / no / don't know)

Documentation

Does this pull request introduce a new feature? (yes / no)
If yes, how is the feature documented? (not applicable / docs / JavaDocs / not documented)

flinkbot · 2026-04-02T07:01:12Z

CI report:

039ac33 Azure: SUCCESS

Bot commands

The @flinkbot bot supports the following commands:

@flinkbot run azure re-run the last Azure build

Copilot

Pull request overview

This PR adds integration tests to the flink-docs module to ensure that generated REST API documentation (HTML + OpenAPI YAML) remains consistent with the committed generated docs, preventing silent drift between code and documentation.

Changes:

Added two REST/OpenAPI docs “completeness” integration tests for Runtime (JobManager/Dispatcher) and SQL Gateway endpoints.
Centralized project-root resolution (rootDir) into org.apache.flink.docs.util.Utils and updated existing tests to use it.
Introduced reusable title constants in the REST OpenAPI generator entrypoints.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
flink-docs/src/test/java/org/apache/flink/docs/rest/SqlGatewayOpenRestAPIDocsCompletenessITCase.java	New ITCase that generates SQL Gateway REST HTML/YAML and compares against committed generated docs.
flink-docs/src/test/java/org/apache/flink/docs/rest/RuntimeOpenRestAPIDocsCompletenessITCase.java	New ITCase that generates Runtime REST HTML/YAML and compares against committed generated docs; provides shared comparison/path helpers.
flink-docs/src/test/java/org/apache/flink/docs/configuration/ConfigOptionsYamlSpecTest.java	Switched project-root lookup to shared `Utils.getProjectRootDir()`.
flink-docs/src/test/java/org/apache/flink/docs/configuration/ConfigOptionsDocsCompletenessITCase.java	Switched project-root lookup to shared `Utils.getProjectRootDir()`.
flink-docs/src/test/java/org/apache/flink/docs/configuration/ConfigOptionsDocGeneratorTest.java	Removed local `getProjectRootDir()` helper now that it lives in `Utils`.
flink-docs/src/main/java/org/apache/flink/docs/util/Utils.java	Added `getProjectRootDir()` utility (supports `-DrootDir` and IDE fallback).
flink-docs/src/main/java/org/apache/flink/docs/rest/SqlGatewayOpenApiSpecGenerator.java	Added `SQL_GATEWAY_OPEN_API_TITLE` constant and reused it.
flink-docs/src/main/java/org/apache/flink/docs/rest/RuntimeOpenApiSpecGenerator.java	Added `RUNTIME_OPEN_API_TITLE` constant and reused it.

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

Copilot · 2026-04-02T08:53:30Z

+import static org.apache.flink.docs.rest.RuntimeOpenRestAPIDocsCompletenessITCase.assertFilesEqual;
+import static org.apache.flink.docs.rest.RuntimeOpenRestAPIDocsCompletenessITCase.getPathOfCommittedHtml;
+import static org.apache.flink.docs.rest.RuntimeOpenRestAPIDocsCompletenessITCase.getPathOfCommittedYaml;


SqlGatewayOpenRestAPIDocsCompletenessITCase depends on helper methods from RuntimeOpenRestAPIDocsCompletenessITCase via static imports. This couples the two ITCases and makes future refactors (renames/moves) harder. Consider extracting these helpers (assertFilesEqual/getPathOfCommittedHtml/getPathOfCommittedYaml) into a dedicated package-private test utility class in org.apache.flink.docs.rest and importing from there in both ITCases.

ForAI:

There will be no high-frequency or large-scale changes here, so the ROI for reuse is quite low.

Introducing new files to store these methods will increase the number of class files.

If placed in the existing Utils, some constant values related to document directories need to be passed frequently; placing test-case-related constants in Utils may not be effective.

RocMarshal · 2026-04-03T04:26:12Z

Hi, masters @reswqa @1996fanrui Could you help take a look ? thanks a lot

1996fanrui

thanks for the improvement to ensure the consistency, lgtm

reswqa

Thanks, LGTM.

snuyanzin · 2026-04-03T07:56:50Z

+    }
+
+    static String readNormalized(Path file) throws Exception {
+        return Files.readString(file, StandardCharsets.UTF_8).replace("\r\n", "\n");


do we really need this?
Asking since we have .editorconfig telling that

flink/.editorconfig

Line 5 in 463330c

end_of_line = lf

and if not
then probably can just use assertJ functionality like

assertThat(pathOfGeneratedHtml.toFile()) .hasSameTextualContentAs(getPathOfCommittedHtml(targetHtmlName).toFile());

and no need for assertFilesEqual at all

Thanks @snuyanzin for the reminder.
You're right.
Updated.

…he generated REST-API related documentation stays consistent with the code. Co-authored-by: 1996fanrui <1996fanrui@gmail.com> Co-authored-by: Sergey Nuyanzin <snuyanzin@gmail.com>

snuyanzin

LGTM
thanks for addressing feedback

RocMarshal

Thanks all reviewers.
Merging...

reswqa requested a review from Copilot April 2, 2026 08:46

Copilot started reviewing on behalf of reswqa April 2, 2026 08:48 View session

Copilot AI reviewed Apr 2, 2026

View reviewed changes

github-actions bot added the community-reviewed PR has been reviewed by the community. label Apr 2, 2026

1996fanrui approved these changes Apr 3, 2026

View reviewed changes

reswqa approved these changes Apr 3, 2026

View reviewed changes

snuyanzin reviewed Apr 3, 2026

View reviewed changes

[FLINK-39359][docs] Introduce integration test cases to ensure that t…

039ac33

…he generated REST-API related documentation stays consistent with the code. Co-authored-by: 1996fanrui <1996fanrui@gmail.com> Co-authored-by: Sergey Nuyanzin <snuyanzin@gmail.com>

RocMarshal force-pushed the FLINK-39359 branch from c14c9cf to 039ac33 Compare April 3, 2026 12:54

RocMarshal requested a review from snuyanzin April 3, 2026 13:47

snuyanzin approved these changes Apr 3, 2026

View reviewed changes

RocMarshal commented Apr 4, 2026

View reviewed changes

RocMarshal merged commit 9b3037b into apache:master Apr 4, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[FLINK-39359][docs] Introduce integration test cases to ensure that the generated REST-API related documentation stays consistent with the code.#27884

[FLINK-39359][docs] Introduce integration test cases to ensure that the generated REST-API related documentation stays consistent with the code.#27884
RocMarshal merged 1 commit intoapache:masterfrom
RocMarshal:FLINK-39359

RocMarshal commented Apr 2, 2026 •

edited

Loading

Uh oh!

flinkbot commented Apr 2, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

RocMarshal Apr 2, 2026

Uh oh!

RocMarshal commented Apr 3, 2026

Uh oh!

1996fanrui left a comment

Uh oh!

reswqa left a comment

Uh oh!

snuyanzin Apr 3, 2026 •

edited

Loading

Uh oh!

snuyanzin Apr 3, 2026

Uh oh!

RocMarshal Apr 3, 2026

Uh oh!

snuyanzin left a comment

Uh oh!

RocMarshal left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Conversation

RocMarshal commented Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What is the purpose of the change

Brief change log

Verifying this change

Does this pull request potentially affect one of the following parts:

Documentation

Uh oh!

flinkbot commented Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CI report:

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

RocMarshal Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

RocMarshal commented Apr 3, 2026

Uh oh!

1996fanrui left a comment

Choose a reason for hiding this comment

Uh oh!

reswqa left a comment

Choose a reason for hiding this comment

Uh oh!

snuyanzin Apr 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

snuyanzin Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

RocMarshal Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

snuyanzin left a comment

Choose a reason for hiding this comment

Uh oh!

RocMarshal left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

RocMarshal commented Apr 2, 2026 •

edited

Loading

flinkbot commented Apr 2, 2026 •

edited

Loading

snuyanzin Apr 3, 2026 •

edited

Loading