Task/69113 keep openapi explorer up to date

[toy]

Ticket

https://community.openproject.org/wp/69113

What are you trying to accomplish?

• Update openapi-explorer
• Fix problem with base tag: openapi-explorer uses pushState with anchor only, but this doesn't work with base tag, as anchor is added to the base url instead of current url
• Fix double scroll on api/docs page

What approach did you choose and why?

• Use openapi-explorer versioned through package.json (and separately bundled) instead of old version in vendor dir
• To fix conflict with base tag:
  • At first two very hacky solutions:
    • hack to resolve base tag conflicting with openapi explorer by not inserting the tag for that page #21060
    • hack to resolve base tag conflicting with openapi explorer by overriding replaceState (+ using pushState instead) #21061
  • Instead in openapi-explorer - navigate to complete url instead of only fragment/hash Authress-Engineering/openapi-explorer#292
• Hacky fix for double scroll by setting openapi explorer parent tag height and width explicitly to prevent the script from forcing 100vw/100vh causing double scrollbars
• Also use RAILS_RELATIVE_URL_ROOT environment variable for dev frontend server (npm run serve) so it affects not only backend paths, but also frontend ones

Merge checklist

• Added/updated tests
• Added/updated documentation in Lookbook (patterns, previews, etc)
• Tested major browsers (Chrome, Firefox, Edge, ...)

[github-actions]

Caution

The provided work package version does not match the core version

Details:

• Work package URL: https://community.openproject.org/wp/69113
• Work package version: not set
• Core version: 17.1.0

Please make sure that:

• The work package version OR your pull request target branch is correct

[Copilot]

Pull request overview

This PR updates the openapi-explorer library from a vendored version to a properly managed npm dependency (v2.4.786), fixing two key issues: a conflict with the HTML base tag that caused navigation problems, and double scrollbars appearing on the API docs page.

Key Changes:

• Migrated openapi-explorer from vendor directory to npm package management
• Added workaround for double scroll issue by explicitly setting parent element dimensions
• Enhanced frontend dev server configuration to respect RAILS_RELATIVE_URL_ROOT
• Added test coverage for the base URL navigation fix

Reviewed changes

Copilot reviewed 4 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
vendor/.keep	Empty file to maintain vendor directory structure after removing vendored openapi-explorer
spec/features/api_docs/index_spec.rb	Adds test verifying that URL fragments are added without changing the base path
frontend/package.json	Adds openapi-explorer dependency and updates serve script with --serve-path parameter
frontend/package-lock.json	Adds openapi-explorer and its transitive dependencies (lit, prismjs, marked, etc.)
frontend/angular.json	Configures bundling of openapi-explorer.min.js as a separate non-injected bundle
app/views/api_docs/index.html.erb	Updates script loading path and adds inline script to prevent double scrollbars

Files not reviewed (1)

• frontend/package-lock.json: Language not supported

[cbliard]

Nice. It's much better than the 2 previous hacks. Thanks for pushing this forward relentlessly.

One thing that seems to not work well is the back button after clicking an OpenProject link. Here is a repro:

• open /api/docs
• click OpenProject logo in top bar
• click back
  • expected: go back to api docs page
  • actual: the url is updated, but the page content is not changed.
  • fun thing: if reloading the page before using the back button, it works as expected (so I think it's related to turbo).

But that should not prevent from merging.

There is also an issue with back button inside the api docs page: it seems to store the same url twice. Here is a repro:

• open /api/docs
• click some links from the left menu
• click back multiple times
  • expected: go back each time back button is pressed
  • actual: have to click twice to get the url updated
  • it was already doing it before, where the url would be /#?route=overview--introduction on first click, then /api/docs#?route=overview--introduction on second click, and so on.

Same, still good to merge IMHO because the behavior is so much better than before.

[toy]

@cbliard Thank you for review and nice finds!

First problem I resolved by disabling turbo on api docs page, so clicking menu links skips turbo which leads to also skipping turbo when navigating back (05f5b94, includes a test)

Second problem is in openapi-explorer => Authress-Engineering/openapi-explorer#293 fixed (c05ed7d)

[cbliard]

Nice one 👏