// Full-Stack Web
ETPA API Documentation Platform
Designed and shipped the ETPA API Hub (docs.etpa.nl), a centralized documentation site that unifies ETPA's multiple API references into one developer-friendly interface for internal teams and external clients. Built on Docusaurus and deployed on AWS (S3 + CloudFront + Route 53) via a GitLab CI/CD pipeline, the hub combines two OpenAPI rendering approaches: the open-source Redoc Standalone component for static references and Redocly's hosted paid platform (embedded via iframe) for interactive endpoint testing on the main ETPA Public API. Documentation stays automatically in sync by fetching OpenAPI specs from live remote sources, with multiple specs (Public API + Reporting API) merged into a single unified UI. The result is a scalable, low-maintenance reference hub that any team can extend without deep framework knowledge.
Overview
Built and shipped the ETPA API Hub (docs.etpa.nl), a centralized reference site that consolidates ETPA's multiple API documentations into a single, developer-friendly interface. The hub gives all ETPA teams and external clients one consistent place to browse, test, and understand our APIs. It's built on Docusaurus and integrates two rendering approaches for OpenAPI specs: the open-source Redoc Standalone component for static references (e.g. the SSE API), and Redocly's hosted paid platform embedded via iframe for the main ETPA Public API, which supports interactive endpoint testing and live code samples. The site pulls OpenAPI definitions from remote sources so documentation stays automatically in sync with the API without manual redeployment.
Challenges
The main constraint was that Redocly's interactive features (API testing, code samples) can only be self-hosted under their Enterprise plan, which was outside our subscription. I had to design an architecture that gave clients the full interactive experience while respecting Redocly's hosting requirements. The solution was to keep docs.etpa.nl as the central hub on our own AWS infrastructure and embed the hosted Redocly instance (api-reference.etpa.nl) through an iframe, cleanly separating what we host from what Redocly hosts. A second challenge was keeping documentation trustworthy over time: since the OpenAPI spec is generated from Swagger annotations in the trader app's source code, the docs are only as accurate as those annotations, so I designed the pipeline around remote content fetching to eliminate stale, manually-maintained copies.
Lessons learned
I learned to treat "build vs. embed" as a real architectural decision rather than a default. Rather than fighting the subscription limitation, embedding Redocly's hosted instance let me ship the interactive experience clients needed without over-engineering. I also came to appreciate single-source-of-truth thinking: having Redocly consume the live OpenAPI JSON directly means the documentation reflects reality automatically, and the real maintenance burden shifts upstream to keeping Swagger annotations accurate, something worth communicating clearly to the dev team. Finally, I saw the value of building for future contributors: documenting how to add new API references (open-source Redoc vs. hosted Redocly) makes the hub extensible without me in the loop.
Architecture
Docusaurus static site hosted on AWS. Content lives as Markdown/MDX pages under /docs, with static assets in /static. Two rendering paths for OpenAPI specs: (1) the RedocStandalone React component renders static specs like the SSE API directly in-page; (2) the main ETPA Public API is served from Redocly's hosted platform and embedded via iframe. Infrastructure: the site builds to static files (npm run build → /dist) and deploys to an S3 bucket configured for static website hosting, with CloudFront for global content delivery and Route 53 for custom domain configuration (docs.etpa.nl). Deployment runs through a GitLab CI/CD pipeline, triggered automatically on merge to main with a manual approval step for the deploy job. Redocly fetches API definitions from a remote source (e.g. the trader app's /v3/api-docs endpoint) and automatically merges multiple OpenAPI JSON files (main API + Reporting API) into one unified UI.