feat: integrate Redocusaurus for interactive OFREP OpenAPI docs page

[jonathannorris]

Integrates Redocusaurus to display interactive OpenAPI documentation for OFREP.

Changes

• Added redocusaurus dependency and preset configuration
• Added scala to Prism syntax highlighting (fixes OpenAPI spec rendering)
• Added docusaurus-theme-redoc theme
• Added custom CSS for full-width Redoc layout while preserving left navigation

Features

• Embedded OpenAPI viewer with left nav visible
• Full-width layout for better API docs readability
• Internal Redoc sidebar hidden (using theme config)
• Search disabled in Redoc viewer

Related PR

Depends on: open-feature/spec#347

[netlify]

❌ Deploy Preview for openfeature failed. Why did it fail? →

Name	Link
🔨 Latest commit	b8173b3
🔍 Latest deploy log	https://app.netlify.com/projects/openfeature/deploys/68f68732f1e32f0008058ae8

[gemini-code-assist]

Summary of Changes

Hello @jonathannorris, 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 introduces interactive OpenAPI documentation for the OFREP specification by integrating Redocusaurus into the existing Docusaurus site. The primary goal is to enhance the user experience for API consumers by providing a dynamic and easily navigable API reference, while maintaining a consistent look and feel with the rest of the documentation.

Highlights

• Redocusaurus Integration: Implemented Redocusaurus to provide interactive OpenAPI documentation for OFREP within the Docusaurus site.
• OpenAPI Spec Display: Configured Redocusaurus to fetch and display the OFREP OpenAPI specification from a remote YAML file.
• Syntax Highlighting Enhancement: Added Scala language support to Prism for improved code block rendering in documentation.
• Custom UI/UX for Redoc: Applied custom CSS to ensure a full-width layout for the Redoc viewer, preserve the existing Docusaurus left navigation, and hide Redoc's internal sidebar and search functionality.
• Dependency Management: Updated project dependencies to include Redocusaurus and its associated packages, along with various transitive dependencies.

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 integrates Redocusaurus to provide an interactive OpenAPI documentation page, which is a great addition. The implementation is mostly solid, with new dependencies and configurations correctly added. I've identified a couple of areas for improvement to enhance build stability and long-term maintainability. Specifically, I've suggested using a permalink for the OpenAPI spec to avoid unexpected build failures and pointed out the use of fragile CSS selectors that could break with future updates. Addressing these points will make the feature more robust.

[gemini-code-assist]

The spec URL for the OFREP API points to the main branch. This can cause build instability if the openapi.yaml file in the open-feature/protocol repository changes. It's better to use a permalink to a specific commit hash or a tag to ensure reproducible builds.

Suggested change

	spec: 'https://raw.githubusercontent.com/open-feature/protocol/refs/heads/main/service/openapi.yaml',
	spec: 'https://raw.githubusercontent.com/open-feature/protocol/COMMIT_HASH_OR_TAG/service/openapi.yaml',

[jonathannorris]

I'm not sure what the best path forward on this is. I kinda like that it just fetches from GitHub for the updated doc automatically, but it does have issues like this. We could easily just have this fetch an updated version of the spec on build, but not sure this repo gets deployed frequently enough for that always to get updated...

[beeme1mr]

I think this is good enough for now. We can update it if we tag a v1 release.

[lukas-reining]

I gave it a try in #1003.

The gist of the feedback was:

It's nice to have the OpenAPI docs included but I'm not sure it makes much sense without more context. What do you think about this?

Hey @beeme1mr this makes sense to me, this is why I was asking for input on it :)

Create a landing page at /doc/reference/technologies/ofrep that explains what it is and why it exists.

Yes this sounds good!

I like the change! And I think the place you chose is better!
Maybe it would be cool to additionally work on the landing page idea in the docs.

[jonathannorris]

yea @lukas-reining we could move this page to the documentation page, and potentially just update the intro description of the OpenAPI spec to be a more descriptive landing page for OFREP. I find it pretty nice for an API like this to just be API docs + interactive spec all-in one.

Getting the CSS and options setup to not show the double left-nav was a bit of a pain, but it fits pretty well now that I was able to remove that.

[lukas-reining]

Getting the CSS and options setup to not show the double left-nav was a bit of a pain, but it fits pretty well now that I was able to remove that.

Oh yes, I remember trying to style it :D

yea @lukas-reining we could move this page to the documentation page, and potentially just update the intro description of the OpenAPI spec to be a more descriptive landing page for OFREP. I find it pretty nice for an API like this to just be API docs + interactive spec all-in one.

Mhhh I think I would like this. On the other hand I am not 100% sure until when this will be good, before we would like to have more structured intro, context, considerations etc. that we would rather like to have on it's own page also in the docs.
Or we do it like you and add a bit more description to the openapi as you said and then add a link to the spec for people that really want to read considerations etc.
I guess I would go for the last option.