Embed the developer portal into an existing website

There are three hosted deployment options for our developer portal (and enterprises may also deploy it on-premise -- out of scope for this article).

1. Whole website. Example: https://www.rebilly.com (the entire website is built on our developer portal software and hosted by us).
2. Subdomain website. Example: https://developers.willowinc.com/ (the developer portal exists on its own subdomain).
3. Embedded website. The embedded website is indicated when you have an existing website you are happy with or don't have the time/resources to port your content to the developer portal. While many will just link to a separate subdomain, it is possible to generate a more seamless approach which makes the portal appear as if it is part of the website.

Proxy request path

1. The web browser makes a request to the proxy.
2. The proxy, in turn, makes a request to Redocly, while keeping the connection open.
3. Redocly responds to the proxy with content (HTML, CSS, JS, images, etc...).
4. The proxy forwards that response onward to the web browser.

Throughout this guide, we'll use https://example.com/docs/ as the path we desire the developer portal to be displayed to users.

Let's say our Redocly project URL is https://example-docs.redoc.ly.

Configuration in Redocly

Proxy path setting

Before you start, navigate to your developer portal in Redocly.

1. Switch to the settings tab.
2. Go to the Advanced tab.
3. Enter /docs and submit the form to change the prefix.

Custom domain setup

Fill in your custom domain.

Because you are using the proxy pattern, you should not change your CNAME record as the screen suggests.

Configure your proxy

This guide shows how to configure a proxy using three examples: nginx, Netlify and AWS API Gateway.

nginx

location /docs/ {
  proxy_ssl_server_name on;
  proxy_pass https://example-docs.redoc.ly/; # trailing slash is important here
}

Netlify

Proxying is part of Netlify's redirects support. To configure redirect and rewrite rules for your Netlify site save a plain text file named _redirects to the publish directory of your Netlify site.

A rewrite rule in the _redirects file for letting parts of your Netlify site proxy to your Redocly developer portal could look like this:

/docs/*  https://example-docs.redoc.ly/:splat 200

Now all requests to /docs/... will be proxied through to https://example-docs.redoc.ly straight from Netlify's CDN servers without an additional connection from the browser.

Keep in mind that proxied URLs won’t be accessible during local development.

AWS API Gateway

Configuration of the AWS API Gateway is more complex than nginx.

First, navigate to your gateway and create a resource.

Then, we create our resource named docs at the resource path /docs.

Next, we'll select our resource and create a child resource for it. Be sure to check the "proxy resource" option.

Fill the form as pictured with proxy as the resource name and {proxy+} as the value. This will catch all requests to its sub-resources which is required for the developer portal.

Next, configure it as an HTTP Proxy and paste in your Redocly project URL https://example-docs.redoc.ly/{proxy} (with the {proxy} at the end).

Be sure the content handling is set to passthrough.

Next, select the /docs resource and then select Create Method from the Actions menu.

Select the integration type as HTTP, paste your Redocly project URL (https://example-docs.redoc.ly/ in this guide) with a trailing slash, and set content handling to Passthrough.

Questions

Have questions? Using a different proxy? Contact us.