feat: add OpenAPI post-processing and improve index generation

[jp-ayyappan]

Summary

• Add `scripts/update-openapi-index.ts` post-processing script that runs after `docusaurus gen-api-docs` to:
  • Rename `.info.mdx` files to `index.mdx` (prevents duplicate sidebar entries)
  • Regenerate `docs/OpenAPI-clients/index.md` with correct directory-based links
• Chain post-processing automatically via `gen-api-docs-all` npm script
• Refactor `preprocessing.ts`: extract shared `SERVICE_DESCRIPTIONS` and `CATEGORY_MAPPING` constants, add catch-all category for uncategorized APIs
• Extend `check-vendored-yaml` to detect unregistered spec files in the platform repo — walks `docs/openapi/` via the GitHub Contents API and fails the build if a new API spec exists upstream without a corresponding entry in `openApiSpecsArray`
• Add footer license info distinguishing Docs (CC BY 4.0) from Code (BSD 3-Clause)
• Add `gray-matter` dependency for frontmatter parsing

Preview

🔗 https://opentdf-docs-preview-openapi-processing.surge.sh

Before vs After

	Before (Production)	After (Preview)
OpenAPI Clients Index	/OpenAPI-clients	/OpenAPI-clients

Preview — API Endpoint Root Pages

These root pages previously did not resolve. This PR fixes them.

Service	Preview Link
Well-Known Configuration	/OpenAPI-clients/wellknownconfiguration
KAS	/OpenAPI-clients/kas
V1 Authorization	/OpenAPI-clients/authorization/v1
V2 Authorization	/OpenAPI-clients/authorization/v2
V1 Entity Resolution	/OpenAPI-clients/entityresolution/v1
V2 Entity Resolution	/OpenAPI-clients/entityresolution/v2
Policy Objects	/OpenAPI-clients/policy
Policy Attributes	/OpenAPI-clients/policy/attributes
Policy Namespaces	/OpenAPI-clients/policy/namespaces
Policy Actions	/OpenAPI-clients/policy/actions
Policy Subject Mapping	/OpenAPI-clients/policy/subjectmapping
Policy Resource Mapping	/OpenAPI-clients/policy/resourcemapping
Policy Obligations	/OpenAPI-clients/policy/obligations
Policy Registered Resources	/OpenAPI-clients/policy/registeredresources
Policy KAS Registry	/OpenAPI-clients/policy/kasregistry
Key Management	/OpenAPI-clients/policy/keymanagement
Policy Unsafe Service	/OpenAPI-clients/policy/unsafe

Related

• Homepage redesign: feat: redesign OpenTDF.io homepage and update documentation styling #191
• License update: chore: update documentation license to CC BY 4.0 #187 (merged)

Test plan

• Run `npm run gen-api-docs-all` and verify no build warnings about missing `.info.mdx` files
• Verify `docs/OpenAPI-clients/index.md` links resolve correctly
• Run `npm run build` and confirm no broken link errors on `/OpenAPI-clients`
• Verify `check-vendored-yaml` fails if a new spec with API paths exists in the platform repo but is not registered in `openApiSpecsArray`

🤖 Generated with Claude Code

[gemini-code-assist]

Summary of Changes

Hello @jp-ayyappan, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the OpenAPI documentation generation workflow by introducing automated post-processing steps. These changes ensure that the generated API documentation is well-structured, correctly linked, and clearly categorized, providing a more user-friendly experience for exploring the platform's services. The update also clarifies licensing information in the site footer.

Highlights

• OpenAPI Post-processing Script: Introduced a new script (scripts/update-openapi-index.ts) to perform post-generation processing for OpenAPI documentation, ensuring correct linking and structure.
• Improved OpenAPI Index Generation: Implemented logic to rename .info.mdx files to index.mdx to prevent duplicate sidebar entries and dynamically regenerate the main docs/OpenAPI-clients/index.md with categorized, directory-based links.
• Automated Workflow Integration: Chained the new post-processing script to the gen-api-docs-all npm command, automating the entire OpenAPI documentation generation and refinement process.
• Refactored OpenAPI Preprocessing: Extracted shared constants (SERVICE_DESCRIPTIONS, CATEGORY_MAPPING) in src/openapi/preprocessing.ts and added a catch-all category for uncategorized APIs, improving maintainability and organization.
• Updated Footer Licensing: Modified the Docusaurus configuration to explicitly state separate licenses for documentation (CC BY 4.0) and code (BSD 3-Clause) in the site footer.
• New Dependency: Added the gray-matter dependency to facilitate parsing frontmatter from Markdown files, used in the OpenAPI index generation.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• docusaurus.config.ts
  • Updated the copyright section in the footer to explicitly state licensing for documentation (CC BY 4.0) and code (BSD 3-Clause).
• package.json
  • Modified the gen-api-docs-all script to sequentially run docusaurus gen-api-docs all --all-versions followed by npm run update-openapi-index.
  • Added a new update-openapi-index script that executes tsx scripts/update-openapi-index.ts.
  • Downgraded minimatch dependency from ^10.2.1 to ^10.0.1.
• scripts/update-openapi-index.ts
  • Added a new script to perform post-processing for OpenAPI documentation.
  • Imports updateOpenApiIndex and renameInfoFilesToIndex from ../src/openapi/preprocessing.
  • Logs messages before and after running the post-processing functions.
• src/openapi/preprocessing.ts
  • Imported the gray-matter library for parsing frontmatter.
  • Introduced SERVICE_DESCRIPTIONS and CATEGORY_MAPPING constants to define API service descriptions and their categorization.
  • Refactored preprocessOpenApiSpecs to no longer create the OpenAPI index page directly.
  • Added renameInfoFilesToIndex function to recursively find and rename .info.mdx files to index.mdx within the OpenAPI output directory.
  • Added updateOpenApiIndex function to dynamically generate the docs/OpenAPI-clients/index.md page with categorized links to API documentation, including a catch-all for uncategorized APIs.
  • Updated the export statement to include the new updateOpenApiIndex and renameInfoFilesToIndex functions.

Activity

• The pull request description outlines a detailed summary of changes, related issues, and a comprehensive test plan.
• No human activity (comments, reviews) has been recorded on this pull request yet.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a post-processing step for OpenAPI documentation generation, which is a great improvement for automating the build process. The refactoring of preprocessing.ts to separate concerns and use constants enhances maintainability. My review includes suggestions to improve code robustness by handling errors more gracefully, enhancing maintainability by adhering to best practices like avoiding inline styles, addressing a potential dependency issue, and a minor performance optimization.

[jp-ayyappan]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a valuable post-processing step for OpenAPI documentation generation, which greatly improves the automation of the docs build. The refactoring of shared constants and the addition of robust handling for uncategorized APIs are excellent enhancements. My review includes a few suggestions for src/openapi/preprocessing.ts to further improve error handling and logging, aiming to make the script more robust and easier to maintain.