Fix openapi/jwt-auth example and add missing example test

[christiangoerdes]

Summary by CodeRabbit

• Documentation

  • Switched the OpenAPI JWT example to a YAML-based configuration, updated headings, and added a step demonstrating access to the protected API before token issuance, with example responses.

• Tests

  • Added end-to-end tests for JWT-protected OpenAPI flows, including dynamic JWK generation, successful access with a valid token, and error handling when a token is missing.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[christiangoerdes]

/ok-to-test

[coderabbitai]

📝 Walkthrough

Walkthrough

Migrates the OpenAPI JWT auth example from XML (proxies.xml) to YAML (apis.yaml), inserts an empty return: {} step into the JWT signing flow, and adds an end-to-end test that generates a JWK, fetches a JWT, and validates protected API access (including unauthenticated rejection) across platforms.

Changes

Cohort / File(s)	Summary
Documentation distribution/examples/openapi/jwt-auth/README.md	Replaced proxies.xml references with apis.yaml examples; converted XML snippets to YAML; reworded headings and reordered sections to add an explicit "try access before token" example and updated responses.
API Flow Configuration distribution/examples/openapi/jwt-auth/apis.yaml	Added an empty flow step - return: {} immediately after the jwk.json location under the jwtSign flow, altering the signing flow sequence.
Integration Test distribution/src/test/java/.../OpenApiJwtAuthExampleTest.java	New test class that generates a JWK (runs generate-jwk via membrane script), fetches a JWT from the Token Server, validates authorized access returns products (200), and validates unauthenticated access returns a 400 security problem; includes cross-platform process handling.

Sequence Diagram(s)

sequenceDiagram
    participant Client
    participant JWK as JWK Generator
    participant TokenServer as Token Server
    participant ProtectedAPI as Protected API

    Client->>JWK: run generate-jwk (create jwk.json)
    JWK-->>Client: jwk.json created

    Client->>TokenServer: GET /  (use jwk for signing)
    TokenServer-->>Client: JWT

    Client->>ProtectedAPI: GET /products (Authorization: Bearer JWT)
    ProtectedAPI->>ProtectedAPI: validate JWT signature (using jwk.json)
    ProtectedAPI-->>Client: 200 + products

    Client->>ProtectedAPI: GET /products (no Authorization)
    ProtectedAPI->>ProtectedAPI: security check fails
    ProtectedAPI-->>Client: 400 security problem

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Possibly related PRs

• add example test #1995 — Related test-infrastructure changes (Process2/env support and service proxy startup helpers) used by the new test.
• openapi + jwt auth example #2061 — Related edits to the OpenAPI JWT auth example (conversion from proxies.xml to apis.yaml and token/protected API wiring).

Suggested reviewers

• rrayst
• predic8

Poem

🐰 I nibble docs and YAML leaves so bright,
I hop to spawn a JWK by night.
Tokens fetched, the API greets,
Unauthorized hops meet gentle beats.
Hooray—small hops make auth just right! 🥕✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title directly and accurately summarizes the main changes: fixing the openapi/jwt-auth example and adding a missing test class.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[membrane-ci-server]

This pull request needs "/ok-to-test" from an authorized committer.

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@distribution/examples/openapi/jwt-auth/README.md`:
- Around line 17-22: The code block fence in the README contains an invalid
opener "```<yaml"; open the README code block that shows the "specs:" YAML
sample and replace the malformed fence with a proper "```yaml" fence so the
snippet renders correctly; specifically update the code fence around the YAML
sample that includes "specs:" / "openapi:" / "location: secure-shop-api.yml" /
"validateSecurity: true" to use a valid YAML code fence.

In
`@distribution/src/test/java/com/predic8/membrane/examples/withoutinternet/openapi/OpenApiJwtAuthExampleTest.java`:
- Line 18: Remove the incorrect static import of org.cef.OS.isWindows and either
replace it with the correct static import
com.predic8.membrane.core.util.OSUtil.isWindows or remove the import entirely
and call OSUtil.isWindows() directly; update the import statement and any call
sites in OpenApiJwtAuthExampleTest to use OSUtil.isWindows (the parent class
DistributionExtractingTestcase already uses that utility), ensuring no
references to org.cef remain.

🧹 Nitpick comments (1)

distribution/src/test/java/com/predic8/membrane/examples/withoutinternet/openapi/OpenApiJwtAuthExampleTest.java (1)

91-96: Process output may not be fully captured after waitFor().

Reading from p.getInputStream() after waitFor() completes can miss output if the buffer was already full during execution (causing deadlock) or if the stream wasn't buffered. Consider reading the output concurrently or using ProcessBuilder.redirectErrorStream(true) with a buffered read during execution.

A safer pattern:

♻️ Suggested improvement

 private static void runGenerateJwk(File dir) throws Exception {
     File jwk = new File(dir, "jwk.json");
     if (jwk.isFile() && jwk.length() > 0) return;

     Process p = createJwkProcess(dir);
+    // Read output during execution to prevent buffer deadlock
+    String output = new String(p.getInputStream().readAllBytes(), UTF_8);
     int exit = p.waitFor();

     if (exit != 0) {
-        throw new IllegalStateException(MessageFormat.format("generate-jwk failed (exit {0}):\n{1}", exit, new String(p.getInputStream().readAllBytes(), UTF_8)));
+        throw new IllegalStateException(MessageFormat.format("generate-jwk failed (exit {0}):\n{1}", exit, output));
     }