OpenAPI: Fix and improve validation, resolve conflicts in endpoint descriptions

[Simran-B]

Description

Even with templates.Defer, we cannot properly trigger /openapi-validate at the end of the Hugo build when all endpoint descriptions are in. A previous sleep of 4 seconds hacked around this issue but to properly address the issue, we need to run the validation after Hugo - which we can only do in static builds but not live builds.

It is still possible to trigger the validation manually in a live build:

docker exec <container-id-of-arangoproxy> curl -s http://localhost:8080/openapi-validate

Things might break when live-editing, because we don't have any logic for replacing OpenAPI descriptions and there will likely be validation errors because of conflicts, but I don't think that we ever supported this.

Upstream PRs

• 3.10:
• 3.11:
• 3.12:
• 4.0:

---

Note

Moves OpenAPI validation to a post-Hugo step with proper error propagation and thread-safe spec aggregation (conflict/duplicate checks), updates templates/linking, and scopes search-alias endpoint paths/operationIds across versions.

• OpenAPI validation (toolchain/arangoproxy):
  • Add thread-safe aggregation with mutexes, counters, and waitgroup; detect duplicate operationIds and method/path conflicts; handle missing versions; return validation errors.
  • ValidateOpenapiHandler now returns HTTP 500 with error details on failures.
  • Write per-version api-docs.json and run swagger-cli validate; surface errors.
• Build script:
  • start_hugo.sh: after a successful Hugo build, call OPENAPI /openapi-validate and fail the build on non-200; environment-aware proxy URL.
• Hugo templates:
  • Fix openapi codeblock link resolution to replace stable|devel with current version; send absolute docs URLs.
  • Remove deferred, Hugo-time OpenAPI validation triggers (baseof.html, openapi-validate partial/shortcode).
• Docs (search-alias Views):
  • Scope endpoints with #searchalias in paths and rename operation IDs to getViewSearchAlias/renameViewSearchAlias for 3.11, 3.12, and 4.0.

^{Written by Cursor Bugbot for commit 5175b16. This will update automatically on new commits. Configure here.}

[arangodb-docs-automation]

Deploy Preview Available Via
https://deploy-preview-835--docs-hugo.netlify.app

[cursor]

This is the final PR Bugbot will review for you during this billing cycle

Your free Bugbot reviews will reset on November 28

Details

Your team is on the Bugbot Free tier. On this plan, Bugbot will review limited PRs each billing cycle for each member of your team.

To receive Bugbot reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.