--- title: "API Gateway with Built-In Developer Portal vs Standalone Documentation Tools" description: "Integrated API gateway with developer portal vs standalone docs tools like Stoplight, Redocly, ReadMe, and Zudoku. A decision framework for API teams." canonicalUrl: "https://zuplo.com/learning-center/integrated-api-gateway-developer-portal-vs-standalone-docs" pageType: "learning-center" authors: "nate" tags: "API Developer Portal, API Documentation" image: "https://zuplo.com/og?text=API%20Gateway%20with%20Built-In%20Developer%20Portal%20vs%20Standalone%20Documentation%20Tools" --- When you need to give developers access to your API, you face an architectural decision that shapes your entire stack: do you pair a standalone documentation tool with a separate API gateway, or do you choose an integrated platform that combines both? Most teams default to the first option without realizing there is an alternative. They pick an API gateway for routing and security, then bolt on a documentation tool for the developer portal. The result is two systems, two deployment pipelines, and an ongoing challenge to keep them in sync. This article breaks down both approaches so you can make the right call for your team, your API consumers, and your operational budget. ## The Two Approaches to API Developer Experience There are two fundamentally different architectures for delivering an API developer experience. **Approach one: standalone documentation tool plus separate gateway.** You pick a documentation platform — Stoplight, Redocly, ReadMe, Swagger UI, or Zudoku — to render your API reference and guides. Separately, you deploy an API gateway — Kong, Tyk, AWS API Gateway, or similar — to handle traffic, authentication, and rate limiting. The two systems share an OpenAPI spec as input, but they are deployed, configured, and maintained independently. **Approach two: integrated API gateway with built-in developer portal.** A single platform handles both the gateway runtime (routing, policies, authentication, rate limiting) and the developer portal (documentation, API key self-service, usage analytics). The OpenAPI spec configures both systems simultaneously, and a single deployment updates everything. The choice between these approaches affects developer experience, operational cost, time-to-market, and how quickly your documentation drifts from your actual API behavior. ## How Standalone Documentation Tools Work Standalone documentation tools follow a consistent pattern. You author or import an OpenAPI specification, the tool parses it, and it generates a static or semi-interactive API reference site. ### What You Get - **API reference documentation** auto-generated from your OpenAPI spec, with endpoint descriptions, request and response schemas, and parameter details - **Interactive try-it consoles** that let developers make test requests from the browser - **Custom pages** for getting-started guides, tutorials, and changelogs written in Markdown or MDX - **Theming and branding** to match your company's visual identity - **Versioning** to display docs for multiple API versions ### What You Do Not Get Standalone documentation tools do not handle live API traffic. They render documentation, but they cannot: - **Manage API keys** — developers cannot create, rotate, or revoke API keys from the portal. You need to build a separate key management system or use your gateway's admin API with a custom frontend. - **Enforce rate limiting** — the portal cannot show consumers their actual rate limit status because it has no connection to the gateway's policy engine. - **Validate requests at runtime** — schema validation happens at the gateway, not in the documentation tool. - **Report usage analytics** — API call volumes, latency, and error rates live in your gateway or observability stack, not in your documentation platform. To fill these gaps, you build integrations. A webhook from the gateway pushes usage data to the portal. A custom backend handles key provisioning. A CI pipeline syncs the OpenAPI spec between your gateway configuration and your documentation tool. Each integration is another piece of infrastructure to build and maintain. ### Popular Standalone Tools **Stoplight** focuses on API design-first workflows with visual OpenAPI editing, linting, and mock servers. It generates documentation from specs and supports Git-based collaboration. Pricing starts at $99 per month for the Starter plan. **Redocly** takes a docs-as-code approach with CLI tooling for linting, bundling, and building. Its open-source Redoc renderer produces clean three-panel API references. The premium tier adds try-it consoles and enhanced search. **ReadMe** provides a managed developer hub with a WYSIWYG editor, interactive API playground, AI-powered search, and built-in analytics focused on documentation engagement metrics. Pricing starts at $79 per month. **Swagger UI** is the open-source default. It renders OpenAPI specs as interactive documentation with a try-it-out feature. It is free but offers minimal customization and no built-in collaboration or analytics. **[Zudoku](https://zudoku.dev)** is the open-source API documentation framework created by the Zuplo team — the same technology that powers Zuplo's own developer portal. It generates interactive API reference documentation from OpenAPI specs, supports custom Markdown and MDX pages, and includes a built-in API playground with real request testing. Zudoku is free to self-host, built on Vite for fast local development, and supports shadcn/ui-compatible theming for brand customization. Scaffold a new project with `npx create-zudoku-app@latest`. Because Zuplo's hosted developer portal runs on Zudoku, teams that start with standalone Zudoku have a straightforward path to Zuplo's full integrated platform when they later need a gateway — the documentation carries over without rewriting. Each of these tools is good at what it does: rendering API documentation. But none of them is an API gateway, and none of them provides the complete self-service developer experience that public API programs require. ## How Integrated API Gateway Plus Portal Platforms Work An integrated platform uses a single OpenAPI specification as the configuration source for both the gateway runtime and the developer portal. When you define a route with authentication and rate limiting policies, the portal automatically documents that endpoint — including the required authentication headers — without any manual synchronization step. ### Architecture: One Spec, Two Outputs In [Zuplo](https://zuplo.com), your `routes.oas.json` file serves as the single source of truth. It is a standard OpenAPI 3.1 document extended with Zuplo-specific configuration (like handler assignments and policy chains). When you deploy: 1. **The gateway** reads the spec to configure routing, authentication, rate limiting, request validation, and all other policies across 300+ edge locations. 2. **The developer portal** reads the same spec to generate interactive API reference documentation, complete with endpoint descriptions, schemas, and a built-in API explorer. 3. **The OpenAPI spec handler** serves a clean, standards-compliant version of the spec (with internal Zuplo extensions stripped out) that consumers can use to generate SDKs or import into their own tools. There is no sync pipeline, no webhook, and no manual documentation update. A single `git push` updates the gateway behavior and the portal simultaneously. ### What You Get Beyond Documentation An integrated platform provides everything a standalone documentation tool offers, plus capabilities that normally require separate systems: - **Self-service API key management.** Developers sign up through the portal, create their own API keys, and start making authenticated requests immediately. No custom backend required. Keys are validated at the edge with global replication in seconds. See [API Key Management](https://zuplo.com/docs/articles/api-key-management) in the Zuplo docs. - **Gateway policies reflected in documentation.** If a route requires API key authentication, the portal automatically documents the `Authorization` header. The docs always match the actual gateway behavior because they are generated from the same source. - **Built-in usage analytics.** API consumers can see how they are using the API, monitor usage of their API keys, and track their consumption directly from inside the portal. - **Rate limiting enforced at the edge.** Configure [rate limiting](https://zuplo.com/docs/articles/step-2-add-rate-limiting) per route, per consumer, or per plan, and developers experience those limits in real time through standard `429 Too Many Requests` responses with `Retry-After` headers. - **Monetization.** Connect Stripe to offer self-service plan selection, payment, and API key provisioning — all within the same portal where developers read your documentation. Zuplo's [monetization feature](https://zuplo.com/docs/articles/monetization/stripe-integration) is currently in public beta. ## Comparing the Two Approaches Rather than a wide feature matrix, here is how the two approaches differ across the capabilities that matter most to API teams. ### Documentation and API Reference Both approaches generate API reference documentation from OpenAPI specs. The quality of the rendered output is comparable — both produce interactive endpoint listings with schemas, parameters, and example responses. The difference is maintenance. With standalone tools, you manage a separate deployment for your docs site. When your API changes, you update the spec in your gateway and then update it again (or trigger a sync) in your documentation tool. With an integrated platform, documentation updates are a byproduct of deploying your API — there is no separate step. ### API Key Self-Service This is the sharpest difference between the two approaches. Standalone documentation tools do not include API key management. Developers cannot create or manage their own keys from the portal. You need to either: - Build a custom key management UI backed by your gateway's admin API - Direct developers to a separate dashboard outside the portal - Provision keys manually and email them to developers With Zuplo, self-service API key management is [built into the developer portal](https://zuplo.com/docs/articles/developer-portal). Developers log in, create keys, and start making requests. Each consumer can hold multiple active keys, and all keys inherit the consumer's metadata (plan, custom attributes) that downstream policies can use for per-consumer rate limiting or feature gating. ### Rate Limiting and Policy Enforcement Standalone documentation tools have no concept of rate limiting. They cannot display a developer's current quota usage or enforce limits — that is the gateway's job. An integrated platform connects these systems. In Zuplo, rate limiting policies are configured per route in the same OpenAPI spec that drives the portal. When monetization is enabled, the portal displays a usage dashboard showing each developer's consumption against their plan limits, providing visibility without any custom integration work. ### Keeping Docs and Runtime in Sync Documentation drift is one of the most common problems API teams face. Your gateway enforces a required query parameter, but your docs do not mention it. Your docs say authentication is optional, but the gateway rejects unauthenticated requests. With standalone tools, drift is a matter of when, not if. The documentation tool and the gateway are separate systems with separate configurations, and any time the two fall out of sync, developers have a bad experience. An integrated platform eliminates drift by design. The same spec file defines both the gateway's behavior and the portal's content. If you add a required header to a route, the portal reflects that change in the same deployment. ### Total Cost of Ownership The licensing cost of a standalone documentation tool is often modest — free for open-source options, $79 to $99+ per month for commercial products. But the total cost of ownership includes more than the license: - **Integration development.** Building and maintaining the pipeline that syncs your OpenAPI spec between the gateway and the documentation tool. - **Custom key management.** Building a frontend and backend for API key provisioning if your gateway does not include a developer-facing portal. - **Operational overhead.** Monitoring, updating, and debugging two separate systems instead of one. - **Documentation drift resolution.** Time spent investigating and fixing discrepancies between what the docs say and what the API does. An integrated platform folds these costs into a single subscription. You pay for one platform, deploy one system, and maintain one configuration. ## When to Choose Standalone Documentation Tools Standalone tools are a legitimate choice in specific scenarios: - **You already have a production API gateway** and only need better documentation. If your gateway is working well and you just want a nicer developer portal, adding a standalone tool is the fastest path. - **Your API is internal-only** and does not need self-service key management, rate limit visibility, or consumer-facing analytics. For internal APIs, documentation alone may be sufficient. - **You need advanced API design tooling.** If your workflow centers on collaborative API design with linting, mocking, and spec governance, tools like Stoplight and Redocly offer mature design-first features. You can use them for design and import the finished spec into an integrated platform for production. - **You require maximum documentation customization.** If your portal requirements go beyond what any integrated platform supports (custom React renderers, deep CMS integration, or non-standard content layouts), a standalone tool gives you more control over the rendering layer. - **You want a free, open-source option with an upgrade path.** Zudoku is completely free to self-host and feature-matched to Zuplo's hosted developer portal. It is a practical starting point for teams that are not yet ready for a full gateway investment but want to avoid re-platforming their documentation later. ## When to Choose an Integrated Platform An integrated API gateway with a built-in developer portal makes sense when: - **You are building a public-facing API** and need the full developer experience — documentation, API key self-service, rate limiting, analytics — without assembling it from multiple tools. - **You want self-service API key management** without building a custom provisioning system. The portal handles the entire lifecycle: creation, rotation, revocation, and usage tracking. - **You want to reduce toolchain complexity.** One platform, one deployment pipeline, one configuration source. Fewer tools means fewer things that can break and fewer vendor relationships to manage. - **You need docs and gateway behavior to stay in sync automatically.** If documentation accuracy is critical for your API consumers, an integrated approach eliminates drift by design. - **You are starting a new API program** and do not yet have a gateway or a documentation tool. Starting with an integrated platform means you never have to build the integration layer between separate systems. - **You want to monetize your API.** Integrated platforms can connect payment processing, plan management, and API key provisioning into a single self-service flow within the developer portal. ## Migration Path: From Standalone Docs to an Integrated Platform If you are currently using a standalone documentation tool and want to move to an integrated platform, the migration is straightforward because both approaches are built on OpenAPI. ### Step 1: Export Your OpenAPI Spec Export the OpenAPI specification from your current tool. Stoplight, Redocly, ReadMe, and Zudoku all support exporting to OpenAPI 3.0 or 3.1 in JSON or YAML format. If you are currently using Zudoku, your migration is especially straightforward — Zuplo's developer portal is built on Zudoku, so your existing docs configuration, custom pages, and theming carry over with minimal changes. ### Step 2: Import into Zuplo Import the spec into Zuplo as your `routes.oas.json`. Zuplo reads standard OpenAPI and adds its own extensions for handler assignments and policy configuration. Your existing endpoint definitions, schemas, and descriptions carry over without modification. ### Step 3: Configure Gateway Policies Add authentication, rate limiting, and other policies to your routes using Zuplo's policy system. These are declared in the same OpenAPI file as extensions, so your documentation and policies are defined together from day one. ### Step 4: Move Custom Documentation Pages If you have getting-started guides, tutorials, or other custom pages in your current documentation tool, move them into the `docs/` folder of your Zuplo project. The developer portal supports Markdown and MDX pages alongside the auto-generated API reference. ### Step 5: Enable API Key Self-Service Configure the API key service and authentication provider in your Zuplo project. Once enabled, the developer portal automatically shows the key management UI to authenticated developers — no custom frontend work required. ### What Stays the Same Your OpenAPI spec remains the center of your workflow. Developers still get interactive API reference documentation with try-it functionality. If you use Stoplight or Redocly for API design, you can continue using those tools for the design phase and import the finished spec into Zuplo for production. ### What Changes You no longer maintain a separate documentation deployment. API key management moves from a custom system (or manual process) to built-in self-service. Documentation drift disappears because the portal and gateway read from the same spec. And your developers get a single portal where they can read docs, get keys, and monitor their API usage. ## Making the Decision The question is not whether standalone documentation tools are good — they are. Stoplight, Redocly, ReadMe, Swagger UI, and Zudoku have helped thousands of teams ship better API documentation. The question is whether documentation alone is enough for your API program. If your developers need to read docs, get API keys, understand their rate limits, and monitor their usage, you have a choice: assemble that experience from multiple tools, or choose a platform that provides it as a unified whole. For teams building public APIs, the integrated approach typically wins on total cost, operational simplicity, and developer experience. For teams with existing infrastructure that just need better docs, standalone tools remain a practical choice. Start building your API with an integrated gateway and developer portal at [zuplo.com](https://zuplo.com). ## Further Reading - [What Is a Developer Portal? The Complete Guide](/learning-center/what-is-a-developer-portal) - [What Is an API Gateway? The Complete Guide](/learning-center/what-is-an-api-gateway) - [Developer Portal Comparison: Customization, Documentation, and Self-Service](/learning-center/developer-portal-comparison) - [How to Create Developer-Friendly API Portals](/learning-center/how-to-create-developer-friendly-api-portals) - [Traditional API Documentation Tools Compared: ReadMe, Redocly, and Swagger](/learning-center/traditional-api-documentation-tools) - [Best API Documentation Tools](/learning-center/best-api-documentation-tools)