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).
- Whole website. Example: https://www.rebilly.com (the entire website is built on our developer portal software and hosted by us).
- Subdomain website. Example: https://developers.willowinc.com/ (the developer portal exists on its own subdomain).
- 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
- The web browser makes a request to the proxy.
- The proxy, in turn, makes a request to Redocly, while keeping the connection open.
- Redocly responds to the proxy with content (HTML, CSS, JS, images, etc...).
- 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.
- Switch to the settings tab.
- Go to the Advanced tab.
- Enter
/docs
and submit the form to change the prefix.
Your sidebars.yaml
and siteConfig.yaml
should define relative paths to the files (e.g. ./my-file.md
and not ./docs/my-file.md
).
Also, your content will not function correctly if you try to access the Redocly project URL (it will only work properly via the proxy).
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.