fix(docs): standardize Java platformEndpoint() to use absolute URLs

[marythought]

Summary

• Update all Java SDKBuilder.platformEndpoint() snippets in authentication.mdx to use absolute URLs (http:// or https://) instead of bare host:port strings
• Fixes 4 occurrences: 2x localhost:8080 → http://localhost:8080, 2x platform.example.com → https://platform.example.com
• Matches the format already used in the Go/JS examples on the same page

Closes #260

Test plan

• Verify authentication page renders correctly
• Confirm all Java snippets now use absolute URL format

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added sorting support to namespace listing: optional sort parameter to order results by name, fully-qualified name, created or updated timestamp, with ascending/descending directions.

• Documentation

  • Updated Java SDK authentication examples to use fully qualified endpoint URLs (http/https) and a dev-only insecure plaintext flag where shown.

[coderabbitai]

📝 Walkthrough

Walkthrough

Added Java docs updates to standardize SDKBuilder.platformEndpoint() examples to absolute URLs; introduced new OpenAPI sorting schemas and a sort field (single-item array) for namespaces list requests.

Changes

Cohort / File(s)	Summary
Java SDK Documentation docs/sdks/authentication.mdx	Replaced bare host:port platformEndpoint values with absolute URLs ("http://localhost:8080", "https://platform.example.com"); added .useInsecurePlaintextConnection(true) // dev only in the Custom Token Source Java snippet.
Policy - Namespaces OpenAPI specs/policy/namespaces/namespaces.openapi.yaml	Added policy.SortDirection enum, policy.namespaces.SortNamespacesType enum, and policy.namespaces.NamespacesSort object; extended policy.namespaces.ListNamespacesRequest with optional sort array (items: NamespacesSort, maxItems: 1).
Policy - Selectors OpenAPI specs/policy/selectors.openapi.yaml	Added policy.SortDirection string enum (values: SORT_DIRECTION_UNSPECIFIED, SORT_DIRECTION_ASC, SORT_DIRECTION_DESC).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 I hopped through docs to tidy each link,
Schemes added neatly—no more missing sync.
Schemas for sorting, a single-item tune,
Namespaces ordered beneath the moon.
Cheers from a rabbit, code-hopping soon! 🥕

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	The PR includes changes to OpenAPI YAML specs (namespaces.openapi.yaml and selectors.openapi.yaml) that are not mentioned in or related to issue #260, which focuses solely on Java documentation fixes.	Remove the unrelated OpenAPI schema changes from this PR or document their necessity; these sorting-related schema additions should be addressed separately if they are separate requirements.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately describes the main change: standardizing Java platformEndpoint() calls to use absolute URLs in documentation, which aligns with the primary objective stated in the PR objectives.
Linked Issues check	✅ Passed	The PR addresses all coding requirements from issue #260: updates Java platformEndpoint() calls from bare host:port to absolute URLs in authentication documentation, matching the objective to standardize across SDK examples.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/260-java-platform-endpoint-urls

---

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.}

[gemini-code-assist]

Code Review

This pull request updates the Java SDK documentation to include protocol prefixes in the platformEndpoint configuration examples. A review comment suggests adding .useInsecurePlaintextConnection(true) to the custom grant example to maintain consistency with other local development snippets in the documentation.

[github-actions]

📄 Preview deployed to https://opentdf-docs-pr-272.surge.sh

[coderabbitai]

🧹 Nitpick comments (1)

docs/sdks/authentication.mdx (1)

99-105: Consider extracting these Java examples into code_samples/.

These are substantial inline snippets; moving them to code_samples/ and referencing them from this page will reduce drift and keep cross-SDK docs easier to maintain.

As per coding guidelines, docs/**/*.{md,mdx}: Keep long examples in code_samples/ and reference them from docs instead of duplicating.

Also applies to: 186-200, 253-263

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/sdks/authentication.mdx` around lines 99 - 105, The inline Java SDK
example using SDKBuilder (calls: platformEndpoint, tokenExchange,
useInsecurePlaintextConnection, build) should be extracted into a standalone
file under code_samples/ (e.g., code_samples/java/authentication.java) and the
docs/sdks/authentication.mdx page should be updated to reference/import that
sample instead of embedding the snippet; move the other long Java blocks noted
(lines ~186-200 and ~253-263) into appropriately named files under code_samples/
and replace each inline example with a brief reference or code import so the MDX
page points to the external samples for maintainability.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@docs/sdks/authentication.mdx`:
- Around line 99-105: The inline Java SDK example using SDKBuilder (calls:
platformEndpoint, tokenExchange, useInsecurePlaintextConnection, build) should
be extracted into a standalone file under code_samples/ (e.g.,
code_samples/java/authentication.java) and the docs/sdks/authentication.mdx page
should be updated to reference/import that sample instead of embedding the
snippet; move the other long Java blocks noted (lines ~186-200 and ~253-263)
into appropriately named files under code_samples/ and replace each inline
example with a brief reference or code import so the MDX page points to the
external samples for maintainability.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 51636db1-4d70-4775-8450-668ea6ab88e7

📥 Commits

Reviewing files that changed from the base of the PR and between ea3882d and e1bbaf0.

📒 Files selected for processing (3)

• docs/sdks/authentication.mdx
• specs/policy/namespaces/namespaces.openapi.yaml
• specs/policy/selectors.openapi.yaml

✅ Files skipped from review due to trivial changes (1)

• specs/policy/selectors.openapi.yaml