Skip to content

ATLAS-5363: Atlas Documentation UI: REST API documentation styling broken on atlas.apache.org due to CSP violation - #721

Open
Brijesh619 wants to merge 3 commits into
apache:masterfrom
Brijesh619:ATLAS-5363
Open

ATLAS-5363: Atlas Documentation UI: REST API documentation styling broken on atlas.apache.org due to CSP violation#721
Brijesh619 wants to merge 3 commits into
apache:masterfrom
Brijesh619:ATLAS-5363

Conversation

@Brijesh619

@Brijesh619 Brijesh619 commented Aug 6, 2026

Copy link
Copy Markdown
Contributor

What changes were proposed in this pull request?

This PR resolves ATLAS-5363 by fixing broken styling and Content Security Policy (CSP) violations on the Enunciate-generated REST API documentation hosted on atlas.apache.org, while updating third-party license declarations per Apache Foundation standards.

Previously, generated API docs relied on external CDNs (bootstrapcdn.com, code.jquery.com, cdn.jsdelivr.net), which were blocked by strict CSP rules, causing unstyled pages and script execution failures.

This patch introduces the following changes:

1. 3rd-Party License & NOTICE Updates

  • Added third-party license text files under 3party-licenses/:
    • bootstrap-LICENSE (MIT License for Bootstrap 3.4.1)
    • jquery-LICENSE (MIT License for jQuery 1.12.2)
    • google-code-prettify-LICENSE (Apache 2.0 License for Google Code Prettify)
  • Updated subcomponent license listings under Apache Atlas Subcomponents: in both LICENSE and docs/src/documents/Project-Info/ProjectLicense.md.
  • Updated copyright range in NOTICE to Copyright [2015-2026] The Apache Software Foundation.

2. Offline CSP Asset Bundling

  • Bundled local static assets in webapp/src/main/enunciate-assets/: bootstrap.min.css, bootstrap.min.js, jquery-1.12.2.min.js, run_prettify.js, and prettify.css.
  • Patched run_prettify.js script loader to derive its base script location dynamically at runtime (W = O.src.replace(...)) and load prettify.css, skins, and lang extensions locally instead of fetching from cdn.jsdelivr.net.
  • Documented jQuery 1.12.2 version pinning for Bootstrap 3.4.1 compatibility in webapp/pom.xml and jquery-1.12.2.min.js.

3. Maven Antrun Execution (fix-enunciate-csp-assets)

  • Renamed antrun execution ID to fix-enunciate-csp-assets and guarded execution with <skip>${skipEnunciate}</skip>.
  • Consolidated repetitive single-file copy tasks into directory <fileset> tasks with failonerror="true".
  • Added build-time <replace> tasks to swap external CDN URLs for relative local asset paths across all generated HTML/JS files in target/api/v2/.
  • Added automated Ant <fail> build-step assertions to verify zero CDN references (bootstrapcdn.com, code.jquery.com, cdn.jsdelivr.net) remain in generated API documentation.

4. Docs & Tooling Enhancements

  • Refactored docs/crypto-fallback.js to safely attempt crypto.createHash('md4') first before falling back to sha256 (Node 17+ / OpenSSL 3.0 compatibility), and logged warnings for ECONNRESET.
  • Restored the Legacy API Documentation link in docs/src/documents/RestAPI.md.

How was this patch tested?

  • Automated License Checks: Ran mvn clean package -pl webapp -DskipTests -DskipEnunciate=true and verified apache-rat-plugin passes with 0 unapproved licenses.
  • Automated Build Assertions: Ran mvn clean package -pl webapp -DskipTests and verified:
    • All <fileset> asset copy tasks executed cleanly with failonerror="true".
    • All CDN URL replacement tasks completed.
    • Automated Ant <fail> assertions verified 0 CDN URLs remain in target/api/v2/.
  • HTML & CSP Verification: Inspected generated target/api/v2/apidocs/index.html and resource pages (data.html, resource_*.html, json_*.html) to confirm all CSS/JS references use local relative paths (css/bootstrap.min.css, js/jquery-1.12.2.min.js, js/run_prettify.js).
  • Docz Site Build: Ran npm run build in docs/ and verified successful site generation (Build successfully created).
  • Browser Testing: Served webapp/target/api/v2/apidocs/ locally and verified in browser DevTools that layout, styling, and code syntax highlighting (run_prettify) load properly with zero CSP console errors.

@Brijesh619
Brijesh619 force-pushed the ATLAS-5363 branch 2 times, most recently from b890258 to 5ebcede Compare August 13, 2026 11:37
Comment thread docs/src/documents/RestAPI.md
Comment thread webapp/src/main/enunciate-assets/js/run_prettify.js
Comment thread webapp/pom.xml
Comment thread webapp/pom.xml Outdated
Comment thread webapp/src/main/enunciate-assets/css/bootstrap.min.css
Comment thread webapp/pom.xml
Comment thread webapp/pom.xml
Comment thread webapp/pom.xml Outdated
Comment thread webapp/pom.xml Outdated
Comment thread webapp/src/main/enunciate-assets/js/run_prettify.js
Comment thread webapp/pom.xml
Comment thread docs/crypto-fallback.js
Comment thread docs/src/documents/RestAPI.md
@Brijesh619

Copy link
Copy Markdown
Contributor Author
Screenshot from 2026-09-04 01-14-37

Comment thread 3party-licenses/bootstrap-LICENSE
Comment thread docs/crypto-fallback.js Outdated
Comment thread docs/crypto-fallback.js
Comment thread webapp/pom.xml
Comment thread webapp/pom.xml
Comment thread webapp/src/main/enunciate-assets/css/prettify.css
Comment thread webapp/src/main/enunciate-assets/js/run_prettify.js
Comment thread docs/package.json Outdated
…oken on atlas.apache.org due to CSP violation
@Brijesh619

Copy link
Copy Markdown
Contributor Author
Screenshot from 2026-09-04 17-02-58

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.

2 participants