Skip to content

Improve OpenAPI (REST) documentation for the website with a docusaurus plugin - #2001

Open
Sziszka90 wants to merge 5 commits into
finos:mainfrom
Sziszka90:feature/open-api-doc-improvement
Open

Improve OpenAPI (REST) documentation for the website with a docusaurus plugin#2001
Sziszka90 wants to merge 5 commits into
finos:mainfrom
Sziszka90:feature/open-api-doc-improvement

Conversation

@Sziszka90

@Sziszka90 Sziszka90 commented Jul 21, 2026

Copy link
Copy Markdown

Describe your change

Integrated Redocusaurus to render the App Directory OpenAPI documentation:

Issue: #1001

  • Added the redocusaurus preset to website/docusaurus.config.js and website/package.json to render OpenAPI specs with Redoc.
  • Added Redoc links to website/sidebars.json and the versioned sidebars (website/versioned_sidebars/version-2.0-sidebars.json, version-2.1-sidebars.json, version-2.2-sidebars.json) so the App Directory API reference is reachable from site navigation.
  • Replaced pathname schema links in website/docs/app-directory/spec.md and website/versioned_docs/version-*/app-directory/spec.md to point at the new Redoc routes.
  • Removed the obsolete generated app-directory.html files under website/static/schemas/2.0, 2.1, 2.2, and next, which are superseded by the Redoc-rendered docs.
  • Updated CHANGELOG.md under Unreleased > Added.

Contributor License Agreement

  • I acknowledge that a contributor license agreement is required and that I have one in place or will seek to put one in place ASAP.

Review Checklist

npm run build
cd website; npm run start
  • Issue: If a change was made to the FDC3 Standard, was an issue linked above?
  • CHANGELOG: Is a CHANGELOG.md entry included?
  • API changes: Does this PR include changes to any of the FDC3 APIs (DesktopAgent, Channel, PrivateChannel, Listener, Bridging)?
    • Docs & Sources: If yes, were both documentation (/docs) and sources updated?
    • Conformance tests: If yes, are conformance test definitions (/toolbox/fdc3-conformance) still correct and complete?
    • Schemas: If yes, were changes applied to the Bridging and FDC3 for Web protocol schemas?
      • If yes, was code generation (npm run build) run and the results checked in?
  • Context types: Were new Context type schemas created or modified in this PR?
    • Were the field type conventions adhered to?
    • Was the BaseContext schema applied via allOf (as it is in existing types)?
    • Was a title and description provided for all properties defined in the schema?
    • Was at least one example provided?
    • Was code generation (npm run build) run and the results checked in?
  • Intents: Were new Intents created in this PR?
    • Were the intent name prefixes and other naming conventions adhered to?
    • Was the new intent added to the list in the Intents Overview?

- Add Redoc links to sidebars.json and versioned sidebars
- Replace pathname schema links in spec.md and website/versioned_docs/*/app-directory/spec.md
- Remove obsolete generated website/static/schemas/*/app-directory.html
- Update CHANGELOG.md (Unreleased → Added)
@Sziszka90
Sziszka90 requested a review from a team as a code owner July 21, 2026 18:37
@netlify

netlify Bot commented Jul 21, 2026

Copy link
Copy Markdown

Deploy Preview for fdc3 ready!

Name Link
🔨 Latest commit f2464eb
🔍 Latest deploy log https://app.netlify.com/projects/fdc3/deploys/6a76ce740ef67f0008302104
😎 Deploy Preview https://deploy-preview-2001.preview-fdc3.finos.org
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@linux-foundation-easycla

linux-foundation-easycla Bot commented Jul 21, 2026

Copy link
Copy Markdown

CLA Signed
The committers listed above are authorized under a signed CLA.

  • ✅ login: Sziszka90 / name: Szilard Ferencz (c466456)

Comment thread CHANGELOG.md Outdated

@kriswest kriswest left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for taking this one on.

I'm having trouble with version selection. Its rendering the next version for me instead of 2.2 when thats selected in teh version.menu top right:

Image

then when the next version is selected it switches to 2.2 when you navigate to it. Hence, this needds a nother look (+conflicts resolving)

@codecov-commenter

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.48%. Comparing base (71e1b59) to head (87d370f).
⚠️ Report is 27 commits behind head on main.

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #2001   +/-   ##
=======================================
  Coverage   95.48%   95.48%           
=======================================
  Files          85       85           
  Lines        6705     6705           
  Branches      873      939   +66     
=======================================
  Hits         6402     6402           
  Misses        303      303           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@Sziszka90

Copy link
Copy Markdown
Author

Thank you for taking this one on.

I'm having trouble with version selection. Its rendering the next version for me instead of 2.2 when thats selected in teh version.menu top right:

Image then when the next version is selected it switches to 2.2 when you navigate to it. Hence, this needds a nother look (+conflicts resolving)

@kriswest Should work now. Can you please retry?

@Sziszka90
Sziszka90 requested a review from kriswest August 7, 2026 17:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants