Embedding the developer portal into an existing website's subdirectory

You can use one of these three hosted deployment options for our developer portal. Enterprises can also deploy it on-premise, but that is out of scope for this topic.

1. Whole website - The entire website is built on our developer portal software and hosted by Redocly. For example, https://www.rebilly.com.
2. Subdomain website- The developer portal exists on its own subdomain. For example, https://developers.willowinc.com/.
3. Subdirectory website. The embedded developer portal is displayed within an existing website you are happy with or do not have the time/resources to port your content to the developer portal. While many organizations may link to a separate subdomain, you can also adopt a more seamless approach which makes the portal appear as if it is part of the website at a subdirectory.

This guide describes how to embed the developer portal into an existing website's subdirectory.

How the proxy request works

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 use https://example.com/docs/ as the path we want the developer portal to be displayed to the users. For the purposes of this guide, our Redocly project URL is https://example-docs.redoc.ly.

Configuration in Redocly

Set up the custom domain

1. In the Redocly app, open the Developer portal you want to embed and select Settings.
2. From the left, select General and under Custom domain, fill in your custom domain and include the subdirectory path. You should enter the full path that you wish to proxy to (for example, www.example.com/docs).

If you are using a proxy, do not change the CName details.

Configure your proxy

The following section shows how to configure a proxy using these services:

• nginx
• Netlify
• AWS API Gateway
• AWS CloudFront

nginx

Add the following code to your nginx configuration file.

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, create and save a plain text file named _redirects to your Netlify site's publish directory.

You can add the following rewrite rule in the _redirects file for letting parts of your Netlify site proxy to your Redocly developer portal.

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

All requests to /docs/... proxy through to https://example-docs.redoc.ly straight from Netlify's CDN servers without an additional connection from the browser.

Note: You cannot access proxied URLs during local development.

AWS API Gateway

To configure AWS API Gateway:

1. Navigate to your gateway resources page and under Actions, select Create Resource.
2. On the Child Resource page, enter docs in the Resource Name field, at the resource path /docs, and select Create Resource.
3. Select the docs resource and create a child resource for it.

4. On the New Child Resource page:

   • Check the proxy resource option.
   • Enter proxy as the resource name.
   • In the Resource path, add {proxy+}. This catches all requests to its sub-resources, which is required for the developer portal.
5. Once you have created the child resource, navigate to the /docs/{proxy+}-ANY-Setuppage.
6. Under Integration type, select HTTP Proxy, and add the Redocly project URL https://example-docs.redoc.ly/{proxy} (with the {proxy} at the end). Ensure the content handling is set to Passthrough.
7. Save your changes.
8. Select the /docs resource, and from the Actions menu, select Create Method.

9. On the /docs-ANY-Setup page,

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

::: warning

Re-deploy your gateway for these changes to take effect, before you use it with Redocly.

:::

AWS CloudFront

To configure AWS CloudFront:

1. On the CloudFront Distributions page, select Create Distribution. The Select a delivery method for our content page displays.
2. On the Select a delivery method for your content page, select Get Started. The Create Distribution page displays.

3. Under Origin Settings, complete the following:

   • In the Origin Domain Name, enter example.com.
   • From Origin Protocol Policy, select HTTPS Only.

4. Under Default Cache Behaviour Settings, select the following:

   • Fromt the Viewer Protocol Policy, select Redirect HTTP to HTTPS.
   • From Allowed HTTP Methods, select GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE.
5. Save your changes. The new distribution is added to the CloudFront Distributions page.
6. Select to view the Distribution details. On the Distribution details page, from the Behaviors tab, select Create Behavior.

7. On the Create Behavior page, complete the following:

   • In the Path Pattern field, enter /docs*
   • From Cache and origin request settings, select Use legacy cache settings.
   • From Object Caching, select Customize.
   • In the Minimum TTL field, enter 86400.
8. Save your changes. The CloudFront Distributions page is updated with a CloudFront Domain Name.

9. Navigate to Portal settings in Redocly Workflows to add the custom domain details to the Portal. There are two ways you can do this:

   • On the Change your custom domain dialog, in the Custom domain field, enter the CloudFront Domain name.
   • On the Change your custom domain dialog, in the Custom domain field, enter example.com/docs.

Questions

Have questions? Using a different proxy? Contact us.