The developer portal beta is approaching end of life.
Use Realm and Reunite instead. Read the migration guide.
- Ensured the
.cachedirectory is automatically created if missing, improving reliability during builds.
- Upgraded the Reference docs package to
2.45.9. Check the Reference docs changelog for details about this version.
- Upgraded the Reference docs package to
2.45.7. Check the Reference docs changelog for details about this version.
- Upgraded the Reference docs package to
2.45.5. Check the Reference docs changelog for details about this version.
- Upgraded the Reference docs package to
2.45.4. Check the Reference docs changelog for details about this version.
- Fixed an issue where the last
hreflink inx-enumDescriptionsOpenAPI section did not apply custompathPrefix, resulting in broken URLs.
- Upgraded the Reference docs package to
2.45.3. Check the Reference docs changelog for details about this version.
- Upgraded the Reference docs package to
2.45.0. Check the Reference docs changelog for details about this version.
- Added an
onClickevent for theWideTilecomponent.
- Add support for an environment variable
LOWERCASE_URLto change tags in the OpenAPI description to lower case when they appear in URLs. - Upgraded the Reference docs package to
2.43.8. Check the Reference docs changelog for details about this version.
- Fixed an issue with duplicated URLs in
sitemap.xml.
- Fixed an issue where users were unable to scroll through Search Results on mobile devices.
- Upgraded the Reference docs package to
2.43.7. Check the Reference docs changelog for details about this version.
- Upgraded the Reference docs package to
2.43.6. Check the Reference docs changelog for details about this version.
- Upgraded the Reference docs package to
2.43.4. Check the Reference docs changelog for details about this version.
- Add expiration date timeout for the authentication token, so logging users out event will be triggered on the UI as expected.
- Authentication tokens expire after the set expiration time, logging users out of the UI as expected.
- Upgraded the Reference docs package to
2.42.4. Check the Reference docs changelog for details about this version.
- Fixed a problem with web-manifest missing
Authorizationheader when Basic authorization applied.
- Fixed a problem with slow build times for OpenAPI files in the
staticfolder. - Prevent OpenAPI files in the
staticfolder from being search-indexed twice.
- Fixed an issue that causes a failing build because of an unresolved
stream.
- Upgraded the Reference docs package to
2.42.1. Check the Reference docs changelog for details about this version. - Upgraded the
@redocly/openapi-corepackage to1.0.2.
- Added support for the
deepLinkPrefixoption with pagination set toitem. - Fixed an issue with copying code snippets text which contains environment variables.
- Added support for the
sideNavStyleconfiguration option that defines the style of the navigation sidebar items (in the left-hand side of the page). The default style issummary-only. Thepath-firststyle shows the path first with the summary underneath. Theid-onlystyle shows the operation ID if provided; otherwise, it shows only the path. - Upgraded the Reference docs package to
2.41.1. Check the Reference docs changelog for details about this version. - Upgraded the
@redocly/openapi-corepackage to1.0.0-beta.131. - Added support for disabling the version log for security reasons.
- Added "404 - Not Found" title to the 404 page.
- Upgraded the
@redocly/openapi-corepackage to1.0.0-beta.124.
- Fixed an issue where a broken page would briefly display prior to redirecting to a different page.
- Fixed an issue with
sitemap.xmlgeneration for large portals.
- Fixed an issue with builds crashing when plugins read data.
- Upgraded the Reference docs package to
2.39.1- check the Reference docs changelog for details about this version.
- Upgraded the Reference docs package to
2.39.0- check the Reference docs changelog for details about this version.
- Fixed an issue where the sidebar disappears periodically.
- Upgraded the Reference docs package to
2.38.2- check the Reference docs changelog for details about this version.
- Upgraded the Reference docs package to
2.38.1- check the Reference docs changelog for details about this version.
- Upgraded the Reference docs package to
2.38.0- check the Reference docs changelog for details about this version.
- Fixed an issue with scrolling to an anchor on initial page loads.
- Fixed an issue with seo
siteUrlconfiguration not working for images. - Fixed an issue with sidebar not hidden on mobile when navigating to different hash link.
- Fixed an issue with hidden search results when closing keyboard area on mobile devices.
- Upgraded the Reference docs package to
2.37.1- check the Reference docs changelog for details about this version. - Upgraded the
@redocly/openapi-corepackage to1.0.0-beta.110.
- Fixed an issue with incorrect search behavior on mobile devices.
- Fixed an issue with showing sidebar scrollbar when there are only a few links in it.
- Fixed an issue with incorrect "Last updated time" for markdown pages in some cases.
- Downloads Redocly configuration files (such as
redocly.yaml) for each API in the API catalog. - Added ability to set search input loading spinner color. Now the theme's
components.search.iconColorproperty applies to the search input loading spinner too. - Upgraded the Reference docs package to
2.36.1- check the Reference docs changelog for details about this version. - Upgraded the
@redocly/openapi-corepackage to1.0.0-beta.109.
- Fixed an issue with search performance where search data loaded multiple times.
- Added possibility to ignore entire folder during the build by placing underscore in front of folder's name. For more details refer to the docs.
- Upgraded the Reference docs package to
2.36.0- check the Reference docs changelog for details about this version. - Upgraded the
@redocly/openapi-corepackage to1.0.0-beta.108.
- Fixed an issue with invalid render order for MDX causing wrong images displayed after page refresh.
- Fixed an issue with invalid error formatting in console output.
- Fixed icon for info admonition.
- Upgraded the Reference docs package to
2.34.0- check the Reference docs changelog for details about this version.
- Fixed an issue with incorrect id for definition, which path is specified under
oasDefinitionssection insiteConfig.yamlbut does not have a corresponding.page.yaml.
Upgraded the Reference docs package to
2.33.0- check the Reference docs changelog for details about this version.Added new theme setting
externalIconUrlto specify URL to external icon. Supports data-urls too. Example usage:const customIconUrl = require('../images/external.svg'); export const theme = { // ... externalIconUrl: customIconUrl, // ... }
- Fixed an issue with not including table content into search results.
- Fixed an issue with rendering mermaid diagrams when portal runs in local environment.
- Added support for wildcard
(*)redirects. You can get more familiar with redirects feature here. - Added export of
Footercomponent, so it can be wrapped in some container. - Added
disableAutoApiDocsconfig option to disable automatic API docs pages creation from OpenAPI files (without .page.yaml). - Added possibility to customize external link icon.
- Upgraded the Reference docs package to
2.31.1- check the Reference docs changelog for details about this version. - Upgraded the OpenAPI Core package to
1.0.0-beta.107.
- Fixed an issue with rebuilding API definition in development mode.
- Added
disableLinkPrefetchingconfig option. If it is set to true, developer portal will do data prefetching only for hovered links. - Upgraded the Reference docs package to
2.31.0- check the Reference docs changelog for details about this version.
- Fixed an issue with portal build failures when image attributes are used on pages.
- Fixed an issue where the customizable images feature was breaking MDX pages if the development server started without the images optimization option.
- Fixed an issue where the search indexer failed for valid OpenAPI definitions.
- Fixed an issue with including jsx tags into search results.
- Added support for
--no-uglifyCLI option to disable JavaScript minification. - Upgraded the Reference docs package to
2.29.0- check the Reference docs changelog for details about this version.
- Fixed an issue where the copy button is not displayed for a code snippet if its language is not specified.
- Fixed a missing alt attribute for
iconinTilecomponents. - Fixed an issue with deprecated
titlewarnings. - Fixed an issue with
drilldownmenu type overlapping. - Fixed an issue with detecting lint ignore file during the portal build.
- Added support for Rudderstack.
- Added new theming options for customizing FAB (floating action button) component.
- Upgraded the Reference docs package to
2.27.3- check the Reference docs changelog for details about this version. - Upgraded the OpenAPI Core package to
1.0.0-beta.105.
- Fixed an issue with the API catalog not working for big API definitions in some cases.
- Fixed an issue with inconsistent behavior for the
deprecatedoption in sidebar menu. - Fixed an issue with div width has value
[object Object].
- Upgraded the Reference docs package to
2.27.1- check the Reference docs changelog for details about this version.
- Fixed an issue when
search-index.jsongot filled with CSS text when using some UI libraries.
- Upgraded the Reference docs package to
2.27.0- check the Reference docs changelog for details about this version. - Upgraded the OpenAPI Core package to
1.0.0-beta.104.
- Fixed an issue with the deprecated
showConsoleparameter. - Fixed a portal crash on an empty
.page.yamlfile. - Fixed title's anchors under the API authentication section.
- Fixed indexing paragraphs on the page for search.
- Upgraded the Reference docs package to
2.26.3- check the Reference docs changelog for details about this version.
- Fixed an issue with page crashing when using custom Navbar and not passing
locationtoSearchBox.
- Upgraded the Reference docs package to
2.26.1- check the Reference docs changelog for details about this version.
- Fixed an issue with top-level sidebar groups not hidden with RBAC if they have nested separator.
- Upgraded the Reference docs package to
2.26.0- check the Reference docs changelog for details about this version. - Upgraded the OpenAPI Core package to
1.0.0-beta.103.
- Fixed an issue with search results not being clickable in some cases.
- Upgraded the Reference docs package to
2.25.1- check the Reference docs changelog for details about this version.
- Upgraded the Reference docs package to
2.23.0- check the Reference docs changelog for details about this version. - Upgraded the OpenAPI Core package to
1.0.0-beta.102.
- Fixed an issue with GraphQL error when set API catalog
disableAutoSidebaroption totrue. - Fixed an issue with search result box show/hide behaviour after the item was selected.
- Upgraded the Reference docs package to
2.22.0- check the Reference docs changelog for details about this version. - Upgraded the OpenAPI Core package to
1.0.0-beta.100.
- Fixed an issue with escaping backslashes when copying code samples.
- Fixed an issue when a page without a footer causes an error.
- Fixed an issue with schemas menu items not working properly.
- Fixed an issue with API catalog not working for API definitions in
jsonformat. - Fixed an issue with cutted off request body in the Try it console.
- Upgraded the Reference docs package to
2.19.1- check the Reference docs changelog for details about this version.
- Fixed an issue with RBAC sidebar items not filtered by default.
- Fixed an issue with the portal not loading API docs for multiple versions of an API when using the
index.page.yamlfile.
- Upgraded the Reference docs package to
2.19.0- check the Reference docs changelog for details about this version. - Upgraded the OpenAPI Core package to
1.0.0-beta.98.
- Resolved an issue with
Code snippetbutton text gets inside the searchIndex. - Resolved an issue with the
WideTileUI component layout.
- Upgraded the Reference docs package to
2.15.0- check the Reference docs changelog for details about this version. - Upgraded the OpenAPI Core package to
1.0.0-beta.97.
- Upgraded the Reference docs package to
2.14.0- check the Reference docs changelog for details about this version. - Upgraded the OpenAPI Core package to
1.0.0-beta.95.
- Resolved an issue with highlighting the last element in the MD(X) page TOC.
- OpenAPI definition files that have
_at the start of the filename will not be included in the portal build.
- Upgraded the Reference docs package to
2.13.7- check the Reference docs changelog for details about this version.
- Resolved an issue with linking to API reference pages from MD pages.
- Upgraded the Reference docs package to
2.13.6- check the Reference docs changelog for details about this version. - Upgraded the OpenAPI Core package to
1.0.0-beta.94.
- Resolved an issue with the portal crashing when non-existing page is referenced from sidebars.
- Resolved a default value for catalog.yaml version summary.
- Upgraded the Reference docs package to
2.13.5- check the Reference docs changelog for details about this version. - Search results on API reference pages will display operation descriptions when available.
- Resolved an issue with
.json-based reference docs pages not working correctly insidebars.yaml.
- Upgraded the Reference docs package to
2.13.4- check the Reference docs changelog for details about this version. - Upgraded the OpenAPI Core package to
1.0.0-beta.93.
- Resolved an issue with missing
setParameterValueexport and fixed a brokenReference docs hookscode example in the documentation. - Resolved an issue with search result disappear on scrollbar click.
- Changed default value for search indexing depth for integrated Reference docs from 8 to 2. Set it to a number from 1 to 10 to control the maximum level of nested properties that should be included in the search index.
- Upgraded the Reference docs package to
2.13.0- check the Reference docs changelog for details about this version. - Upgraded the OpenAPI Core package to
1.0.0-beta.91.
- Resolved an issue with portal crashing builds on invalid
.yamlfiles.
Implemented the API catalog - a new approach for integrating the developer portal and the API registry. Use the
catalog.yamlfile to import assets and integrate multi-version APIs into your portal.You can add an "Edit page" button to all or some MD(X) pages in your portal. When enabled, the button is displayed at the top of each page, and can link to a GitHub or a GitLab repository. You can enable it globally for all pages in the
siteConfig.yamlfile, or control it per-page in the front matter.Starting with this release, portal version number is visible in the developer console to make troubleshooting easier.
Reference docs pages can be integrated directly into the portal without creating
.page.yamlfiles. To achieve this, add your OpenAPI definition file to the portal project and include it into asidebars.yamlfile. Note that this approach doesn't support multi-version APIs, integrating APIs from the Redocly API registry, restricting permissions with RBAC, or excluding specific API reference documentation from portal search results. To use those features, you have to integrate Reference docs with.page.yamlfiles as before.
- Wildcard
/*links (e.g.acme.page.yaml/*) for adding Reference pages to the portal sidebar are deprecated for the direct OpenAPI file integration. Those links only work when using.page.yamlfiles to integrate Reference docs into the portal.
- Upgraded the Reference docs package to
2.12.5- check the Reference docs changelog for details about this version. - Upgraded the OpenAPI Core package to
1.0.0-beta.88which allows using theredocly.yamlname for the configuration file. - All table of contents sections on MD(X) pages have an "On this page" header.
- Implemented support for displaying a sidebar on pages not listed in any
sidebars.yamlfile. To do this, use the newsidebaroption in the page front matter. Specify which sidebar to display by providing the path to thesidebars.yamlfile or the sidebar name (if you're using the legacy sidebar configuration withsidebarName).
Usage example
---
title: Adding sidebar to the page
sidebar: training
------
title: Adding sidebar to the page
sidebar: ../sidebars.yaml
---If you have defined multiple sidebars in the root sidebars.yaml file, the portal displays the first available sidebar from that file when you add its path to the front matter. In this case, we recommend you use the sidebar name in the front matter to precisely control which sidebar to show. Front matter has priority over other configuration. If a page is listed in a sidebars.yaml file and has a different sidebar set in the front matter, the one from the front matter displays.
- Resolved an issue with
disableImagesOptimizationnot working due tosharpdependency.
- Implemented support for API registry links on the
redocly.comdomain. - Upgraded the Reference docs package to
2.12.3- check the Reference docs changelog for details about this version.
- Resolved an issue with Markdown references to symlinks.
- Implemented support for linting API definitions from the API registry. To use this feature, either add the
--lint-registry-definitionsoption to the portal build command, or set up theREDOCLY_LINT_REGISTRY_DEFINITIONSenvironment variable. - Upgraded the Reference docs package to
2.12.2- check the Reference docs changelog for details about this version.
- Resolved an issue with the link checker in preview builds.
- Resolved an issue with the
GithubSluggerimport when upgrading to a new portal version. - To improve the security of portal dependencies, we migrated from
shortidtonanoidpackage. - Resolved an issue with incorrect spacing in nested lists
- Upgraded the Reference docs package to
2.11.11- check the Reference docs changelog for details about this version.
- Resolved an issue with RBAC not applying configured permissions to assets (linked files).
- Resolved an issue with mutation breaking RBAC in build mode.
- Upgraded the Reference docs package to
2.11.6- check the Reference docs changelog for details about this version.
- Resolved an issue that caused
classNameerrors in the browser console on MDX pages. - Resolved an issue that caused warnings about resolving dependencies in the build log.
- Resolved an issue with request body example linting in OpenApiTryIt component.
- Added support for Google Optimize. Read how to configure it for your portal on the Analytics page.
- Upgraded the Reference docs package to
2.11.1- check the Reference docs changelog for details about this version.
- Resolved an issue with hot-reloading of OAS definition files.
- Resolved an issue with invalid mobile sidebar icon color in some cases.
- Resolved an issue with Gatsby version update crashing builds.
- Resolved an issue with support for multiple
sidebars.yamlfiles on Windows.
- Resolved an issue with build failure on Node 17.x.
- This release adds support for multiple
sidebars.yamlfiles and introduces changes to sidebar configuration in the portal. For complete instructions, make sure to read the migration guide. - Upgraded the Reference docs package to
2.9.4- check the Reference docs changelog for details about this version.
- Upgraded the Reference docs package to
2.9.1- check the Reference docs changelog for details about this version.
- Upgraded the Reference docs package to
2.8.3- check the Reference docs changelog for details about this version.
- Resolved an issue with Navbar mobile menu disappears on the medium breakpoint.
- Resolved an issue with missing area-label in the search input.
- Upgraded the Reference docs package to
2.8.2- check the Reference docs changelog for details about this version.
- Locked the
openapi-clipackage version to1.0.0-beta.67. - Upgraded the Reference docs package to
2.8.1- check the Reference docs changelog for details about this version.
- Resolved an issue with broken links to security in preview.
- Added a new experimental feature
--prefix-assets(can also be used as an environment variableREDOCLY_PREFIX_ASSETS). This is useful in cases when you need to set a custom prefix for all asset paths in order to load them from an external resource. - Upgraded the Reference docs package to
2.7.9- check the Reference docs changelog for details about this version.
- Resolved an issue with dynamic hashes that were not properly stripped from canonical URLs.
- Resolved an issue with prefixing search index with env variable
REDOCLY_PREFIX_ASSETS.
- Upgraded the Reference docs package to
2.7.4- check the Reference docs changelog for details about this version.
- Resolved an issue with the color of
Delete appbutton in Apigee portal - changed it to primary. - Resolved an issue with broken links inside the Reference docs Markdown descriptions.
- Added support for amplitude analytics. For configuration settings check this page.
- Added possibility to exclude page url from sitemap.xml using
excludeFromSearchoption in frontmatter. securityDefaultsproperty ofOpenApiTryItcomponent can now accept a function. The number of function arguments depends on the number of dependencies specified in theneedsproperty. Each argument should be provided in the form of a{ request, response }object.- Added new component
ExplainStep. It is designed to enhance Step by Step Guides with tips and instructions for every step.
Usage Example
import {
OpenApiTryIt,
Alert,
scrollToHeading
} from '@redocly/developer-portal/ui';
## Step 1: Upsert a customer
<OpenApiTryIt
definitionId="core"
operationId="CreateUser"
id="step-1"
/>
<ExplainStep
needs={['step-1']}
placeholder={(step1) => {
if(!step1) {
return (
<Alert variant="danger">
We should take <strong><i>data.user.id</i></strong> from the body of the response
and use it as a <strong><i>userId</i></strong> query parameter in the next requests.
</Alert>
)
} else {
return (
<Alert variant="success">
<strong>User Id: {step1.response.body.data.user.id}</strong>
</Alert>
)
}
}}
/>
## Step 2: ...
- Resolved an issue with missing
copybutton in Markdown snippets. - Resolved an issue with hash links to integrated Reference pages not working properly when pagination is set to
none.
- Upgraded the Reference docs package to
2.7.0- check the Reference docs changelog for details about this version. - New utility function
scrollToHeadingexported from@redocly/developer-portal/ui. - Added a number of new properties to the
OpenApiTryItcomponent to help you create interactive step-by-step guides. The new properties are:id(optional)needs(optional)placeholder(optional)serverVariables(optional)
id property is required if subsequent OpenApiTryIt instances rely on the response of the current component.
needs property should contain an array of Ids of preceding OpenApiTryIt components if it relies on their response bodies.
placeholder accepts a function that returns a component that is shown instead of OpenApiTryIt if it does not have enough information to perform a "Try It" request.
serverVariables accepts an object or a function that should return an object with server variables overrides. In case it's a function, the number of its arguments depends on the number of dependencies specified in the needs property. For more information about server variables, please, follow this link. You can also check out the example below.
We also improved some of the existing properties in the component:
propertiescan now accept a function. The number of function arguments depends on the number of dependencies specified in theneedsproperty. Each argument should be provided in the form of a{ request, response }object. The function should return a new object that is merged with the default body schema.parameterscan now accept a function. The number of function arguments depends on the number of dependencies specified in theneedsproperty. Each argument should be provided in the form of a{ request, response }object.the
defaultExampleproperty now can take thefalsevalue. In this case, the Request Body inOpenApiTryItcomponent is entirely overridden by the user-providedpropertiesobject.
Usage Example
import {
OpenApiTryIt,
Alert,
scrollToHeading
} from '@redocly/developer-portal/ui';
## Step 1: Upsert a customer
<OpenApiTryIt
definitionId="core"
operationId="CreateUser"
id="step-1"
properties={{
firstName: "John",
lastName: "Smith"
}}
serverVariables={{
// Example of server url: https://api.example.com/org/{organizationId}
organizationId: {
default: 'Google',
enum: ['Redocly', 'Rebilly']
}
}}
onResponse={({ response }) => {
if (response.ok) {
scrollToHeading('#step-2-create-an-order')
}
}}
/>
We need to use the userId in the next request.
## Step 2: Create an order
<OpenApiTryIt
definitionId="core"
operationId="PlaceOrder"
id="step-2"
needs={['step-1']}
properties={{
cartId: '8bb31d4b-0b88-4a29-9f08-a2af65f95dcf'
}}
parameters={(step1) => ({
query: {
userId: step1.response.body.data.user.id
}
})}
placeholder={(step1) => {
return <Alert variant="warning">Please complete step 1</Alert>
}}
/>
- Resolved an issue with missing
descriptionin typeContentItemSeotype. - Resolved an issue with Node 17 compatibility.
- Resolved an issue with overriding parameters in
OpenApiTryItcomponent when parameters in definition are defined on the path item level. - Resolved an issue with Reference docs anchor links in Developer portal preview builds.
- We have reorganized configuration options for modifying the
<head>contents in your portal. Instead of adding these options to themetasection insiteConfig.yamlor to the top level of page front matter, you should now define them in a new section called seo. This means you can now use the same configuration syntax in front matter and insiteConfig.yaml- a big win for consistency!
Specifically, this affects the following configuration options:
descriptionimagekeywordstitlelangsitemapin front mattersiteUrlin thesiteConfig.yamlfile
and the x-meta specification extension supported in integrated Reference docs pages.
Compare the previous and the new configuration approach.
- meta:
- title: Example Developer Portal
- description: The best portal ever
- image: example.png
- keywords: documentation,portal,api
-
+ seo:
+ title: Example Developer Portal
+ description: The best portal ever
+ image: example.png
+ keywords: documentation,portal,api
+- ---
- title: Supported Markdown features
- description: Using Markdown in your developer portal
- keywords: markdown,portal,documentation
- ---
-
+ ---
+ seo:
+ title: Supported Markdown features
+ description: Using Markdown in your developer portal
+ keywords: markdown,portal,documentation
+ ---
+We recommend migrating to the new configuration approach as soon as possible. Although currently supported, the old approach is considered deprecated and reports warnings in the portal build log.
- You can now set up JSON-LD parameters for your portal in the
siteConfig.yamlfile or in the front matter for individual MD(X) pages in the portal. - Upgraded the Reference docs package to
2.6.1- check the Reference docs changelog for details about this version. - Upgraded the latest version of the
openapi-clipackage.
- Resolved an issue with TOC anchor links scrolling to a wrong area on a second click.
- Resolved an issue with broken absolute links in previews.
- Resolved an issue with symlinked Markdown files referenced from MDX files causing the build to crash.
- Resolved an issue with the
sitemap.xmlfile not found. - Resolved an issue with absolute links without path prefixes in Markdown snippets and MDX pages.
- Resolved an issue with the Reference docs version switcher getting overlapped when used with a drilldown-style sidebar.
- Resolved an issue with H1 headings from Markdown files not used in sidebar labels.
- Upgraded the Reference docs package to
2.4.0- check the Reference docs changelog for details about this version.
- Resolved an issue with the portal page table of contents not working with headings from reusable Markdown snippets.
Broken release.
- Upgraded the Reference docs package to
2.4.0- check the Reference docs changelog for details about this version.
Resolved an issue with the portal unnecessarily linting definitions from the registry when they should be skipped.
Resolved an issue with code block formatting inside the
JsonSchemacomponent.Resolved an issue with the
selectFirstItemOnExpand: truesidebar setting not working when RBAC is set up for the portal.
- Reverted a change to page TOC anchor links that caused issues in the previous two releases.
Broken release.
Broken release.
Updated the
openapi-corelibrary with the latest version ofjs-yamlthat includes fixes for recent issues.Resolved an issue with integrated Reference docs crashing when using custom components that override the ThemeProvider.
- Reverted the change that added
js-yamlfromopenapi-corein the previous version.
The
onResponsecallback option in theOpenApiTryItcomponent now supports therequestargument that allows it to inspect request data after performing a request.The
OpenApiTryItcomponent now supports thesecurityDefaultsproperty that allows users to specify default values for security schemes in their example requests.When using the
Linkcomponent for custom login pages,previousPathnow is present inlocation.state. This can be useful to get the referrer page and redirect back to it after the login.Upgraded the Reference docs package to
2.3.0.Added the
js-yamlpackage fromopenapi-coreand removedjs-yamlfrom portal dependencies.
- The portal now supports a global configuration file for custom redirects. The file must be named
redirects.yamlorredirects.jsonand stored in the root directory of the portal project. The contents of the file should map each source URL to one or more destination URLs, and optionally specify the redirect type. Here's an exampleredirects.yamlfile:
'/some-old-url/':
to: '/new-url/'
type: 301
'/some-other-old-url':
to: '/new-url/'Resolved an issue with
+symbol encoding inoperationIdvalues and in file names.Emacs lock fils are now automatically ignored to prevent crashing the portal on some file systems.
You can now set the default MIME type for code samples in the
OpenApiCodeSamplecomponent. Use thedefaultMimeTypeconfiguration option to set the default MIME type, and theonlyDefaultMimeTypeoption to show only the preset MIME type in code samples. This feature is entirely optional, and code samples retain their previous behavior if these options are omitted.The
OpenApiTryItcomponent now supports an optionalonResponsecallback that can be used to work with the response data after a successful request. In the following example, the callback is used to forward the response data to the log:
<OpenApiTryIt
definitionId="petstore"
operationId="addPet"
defaultExample="bee"
onResponse={(data) => console.log('data: ', data)}
/>You can now configure search indexing depth for integrated Reference docs with the
searchMaxDepthoption. Set it to a number from 1 to 10 to control the maximum level of nested references that should be included in the search index. The default value is 8.Your portal visitors can now interactively resize the columns in any table by dragging the separators between column names in the table header.
Upgraded the Reference docs package to
2.1.24- check the Reference docs changelog for details about this version.
Resolved a sidebar scrolling issue when using
menuStyle: drilldownwhich resulted in the sidebar content overlapping and displaying duplicated artifacts.Resolved an issue with the page table of contents exceeding the page width.
- Removed unnecessary border styling around code blocks.
- Markdown code blocks now have a handy Copy button, so you can copy the entire code block with one click! This feature is global (affects all pages in the portal) and it's enabled by default in the
1.1.0-beta.55version.
To disable it, add the following to your siteConfig.yaml file:
copyCodeSnippet:
enable: falseThe copyCodeSnippet section supports options for configuring the copy button and the notification that appears after selecting it. Read more about it in the siteConfig documentation.
- You can now use the
schemaExpansionLevelproperty in Portal components to set the default expansion behavior for schemas. To expand the whole schema contents, set it toall. If you set it to a specific number, schemas are expanded only up to that level. For example,schemaExpansionLevel: 3automatically expands schema contents up to three levels.
The following Portal components support the schemaExpansionLevel property:
JsonSchemaOpenApiCodeSampleOpenApiExampleOpenApiRequestBodyOpenApiResponseOpenApiTryIt
To configure the schema expansion level, add the property to the options object when inserting the component into a page.
- Resolved an issue with the background color of code blocks in MD(X) pages.
Resolved an issue with search indexing of schema field names in the
JsonSchemacomponent.Resolved a padding issue in the search box which caused the search icon to cover the text.
Resolved a caching issue with the local development server.
- Resolved issues with the page ToC links, and ToC settings for backwards compatibility.
- Resolved issues with the logo settings. For backwards compatibility, if there is no logo
hrefdefined, we default to/.
- Resolved issues with inline code styles, and missing page ToC.
- Upgraded the Reference docs package to
2.1.21- check the Reference docs changelog for details about this version.
Implemented support for customizing the sitemap record for specific pages in the portal. This functionality is provided by the gatsby-plugin-sitemap plugin.
Upgraded the Reference docs package to
2.1.17- check the Reference docs changelog for details about this version.
- Resolved a theming issue with the text color of response headers in integrated Reference docs. The
theme.colors.responses[type].colornow properly modifies the response header text color.
- Upgraded the Reference docs package to
2.1.14- check the Reference docs changelog for details about this version.
- You can now use two new React components in your portals:
OpenApiCodeSampleandOpenApiTryIt. Add them to MDX pages and create step-by-step guides to teach your API consumers how to build and integrate with your APIs. These components bring in the Try It console functionality and interactive request code samples from Redocly Reference into your portal pages to help you design a consistent, seamless developer experience. Both components are highly customizable, allowing you to preset default values in request examples, control the appearance of code sample tabs, and use auto-generated code samples.
- We have simplified and consolidated the table of contents (ToC) configuration options. Instead of adding multiple separate top-level items to your
siteConfig.yamlfile, you can now control all ToC-related options in one place.
That place is the new toc section in siteConfig.yaml. It supports the following options:
enable- boolean, replacesenableTocmaxDepth- number, replacestocMaxDepth, requiresenable:true
Compare the previous and the new approach to configuring the ToC. The same syntax works in siteConfig.yaml and in page front matter.
- meta:
- title: Example Developer Portal
- enableToc: true
- tocMaxDepth: 4
-
+ meta:
+ title: Example Developer Portal
+ toc:
+ enable: true
+ maxDepth: 4
+We recommend migrating to the new ToC configuration approach as soon as possible. Although currently supported, the old approach is discontinued in one of the upcoming Portal releases.
- The table of contents is now supported in MDX pages and can be configured in their front matter (just like for MD pages). If the TOC is configured globally in the
siteConfig.yamlfile, it is now displayed on MDX pages, too.
- Resolved an issue with the invisible sidebar button in mobile view when the primary color in the portal theme is set to white.
- Upgraded the Reference docs package to
2.1.12- check the Reference docs changelog for details about this version.
- Resolved an issue with Webpack that appeared when using
buildandstartcommands.
- Your portal logo image can now open any custom URL when clicked, so it's no longer just decorative, but useful too! To set the custom URL, add it as the value of the
logoHrefoption in themetasection of yoursiteConfig.yamlfile.
- Resolved a layout issue that appeared in landscape mode on iPhone X devices.
- Upgraded the Reference docs package to
2.1.10- check the Reference docs changelog for details about this version.
- Resolve partially corrected issue with the
colorettedependency from the previous release.
- Upgraded the Reference docs package to
2.1.7- check the Reference docs changelog for details about this version.
- Resolved an issue with the broken
colorettedependency that would cause a crash after updatingyarn.lock.
Resolved an issue with RBAC portals crashing post-build because of invalid
pages: nullvalues in the sidebar.Resolved an issue with crashed RBAC portal builds not reported as failed.
- Upgraded the Reference docs package to
2.1.4- check the Reference docs changelog for details about this version.
- Customers who use our Apigee integration notice the App page has been fully redesigned, and now includes more detailed information on the API key status.
Upgraded the Reference docs package to
2.1.2- check the Reference docs changelog for details about this version.Implemented support for custom sanitize hooks in overrides.
- Resolved an issue with
logoutUrl.
- User claims and
idpIdare now supported in the login hook.
- Upgraded the Reference docs package to
2.0.15- check the Reference docs changelog for details about this version.
Fixed a typo in the build error message displayed when a snippet file is not found.
Resolved a styling issue with portal search results that were displayed in white text on a white background.
Resolved an issue with hook ordering that caused crashes for some customers.
You can now use the
LoginMenucomponent in custom overrides; for example, when you want to override the navbar but still use the default login menu.A new hook called
OnPaginationis now supported for integrated Reference docs, and runs on pagination between Reference docs pages.Upgraded the Reference docs package to
2.0.14- check the Reference docs changelog for details about this version.
- Upgraded the Reference docs package to
2.0.13- check the Reference docs changelog for details about this version.
- Upgraded the Reference docs package to
2.0.12which fixes the issue withenumvalues not displaying properly, among other improvements. Check the Reference docs changelog for details about this version.
- Implemented basic support for the
x-metaspecification extension for integrated Reference docs. Add it to your API definition on the operation level to control meta tags for each page (operation). The prerequisite is that your Reference docs haspagination: itemconfigured. Here is a basic example of thex-metasyntax:
x-meta:
title: title
description: descr
keywords: test1, test2
image: https://- Upgraded the Reference docs package to
2.0.11and implemented all fixes to integrated Reference docs. Check the Reference docs changelog for details about this version.
- When users search for information in your developer portal, the results are now more accurate thanks to improved search weights. More specifically, pages with titles that match the search query now appear higher in the list of results than the pages that only match the query in the text body.
- Resolved an issue with the order of React hooks that could crash on Reference docs pages in the portal.
- Upgraded the Reference docs package to
2.0.10- check the Reference docs changelog for details about this version.
Resolved an issue with the Ctrl+F browser search override not working on Reference docs pages in the portal.
Resolved an issue with the Link React component that would cause a circular import crash when used in a specific way with
_override.Resolved an issue with an extra path prefix in
unauthorizedTryIt.link.
Improved the order of search results so that more accurate results are displayed first.
Resolved an issue with the login menu not showing up for some users.
Resolved an issue with protected registry URLs that were not working correctly.
This major Developer portal release introduces support for Reference docs 2.0 and brings a complete visual overhaul to your integrated API reference docs.
It also introduces:
major changes to the
ButtonReact component usagethe latest version of the
openapi-clipackage
For the full list of changes and upgrade instructions, make sure to read the migration guide.
Developer portal users can downgrade their portal version to 1.0.0-beta.162 to use the old Reference docs design.
Internal releases.
- Resolved a Webpack issue with build and start commands.
- Resolved an issue with Emacs lock files that caused portal crashes on some file systems.
- Backported a
ttyfix from the1.1.0-beta.xrelease channel.
Internal changes.
- When users search for information in your developer portal, the results are now more accurate thanks to improved search weights. More specifically, pages with titles that match the search query now appears higher in the list of results than the pages that only match the query in the text body.
Internal release.
You can now set the
langproperty for your portal to indicate the language of your content. To set it globally for the entire portal, add it to the meta section of thesiteConfig.yamlfile. You can also override the global setting for individual pages by setting it in the page front matter.The developer portal theme now supports a new
marginoption in thelogosection. To configure it, you can use one value (applies the same margin to all sides of the image) or specify up to four separate values. The values must follow the standard CSS margin property syntax.
Resolved an issue with custom data loss when using
createTemplatePageinsidecreatePagescaused by thesourcePathhook.Resolved an issue with portal builds crashing when Markdown-style image formatting was used in MDX pages.
- The logo image displayed in the portal navbar can now have custom alt text. To add it, use the
logoAltTextoption in the meta section of thesiteConfig.yamlfile.
- Resolved a Windows issue with custom CSS imports and images in Markdown snippets.
- Resolved an issue with processing
.sample.jsimports.
- Resolved an issue with broken absolute links in reusable snippets.
- You can now import raw code samples from standalone files into MDX pages. The approach is similar to how you would import a React component. Save your code sample as a file in your portal project with the
.sample.extextension, whereextmatches the code language extension (py,js...). Then, import it at the beginning of your MDX page and insert it in the page body like in this example:
import codeSample from './code-samples/code.sample.js';
# Page title
Page text
## Example section with code sample
<pre><code>{codeSample}</code></pre>Resolved an issue with local CSS stylesheets not working for some Windows users.
Improved the approach to calculating the last modified date for pages. Additionally,
lastModifiedis now available throughpageContextglobally.
- Resolved issues caused by a conflicting dependency.
- Resolved a version compatibility issue with the
gatsby-remark-image-attributesplugin.
Upgraded the Reference docs package to the latest version (
1.5.13).Resolved an issue that prevented the Try it console in integrated Reference docs from functioning properly.
Improved the print CSS stylesheets and removed the portal navbar from the print layout.
Resolved a regular expression issue in the Apigee integration.
- Improved support for Markdown snippets makes it possible to use admonitions, links, images and code blocks in your reusable snippet files. Snippets are no longer limited only to Markdown target pages - you can now use them in MDX pages as well.
- Resolved a URL-encoding issue with developer email addresses for the Apigee integration that contain the
+symbol.
- When inserting images into your Markdown pages, you can now specify their size. Supported image size parameters are
widthandheight, and you can set both or just one for each image. The following example illustrates how to insert a resized image:
- Resolved an issue with illegible content in the JsonSchema component caused by a dark background.
- Developer portal pages are now more printer-friendly thanks to improvements to the print CSS stylesheet.
- The login component in the portal navbar now supports redirecting to a custom URL after users log out of the portal. You can set the custom URL in the
login.menusection of thesiteConfig.yamlfile. Refer to the login component documentation for more details.
- Resolved an issue with inconsistent dependencies that crashed the build after performing a clean install of the portal.
- Automatic exclusion of the top-level
README.mdfile now works as intended. If your portal has this file in the root of the project, it is now automatically excluded from the portal build and from search.
- Resolved an issue with the search functionality that prevented the search results from including all scopes.
- Implemented support for controlling access to portal sidebars with RBAC.
- Long headings in MD(X) page table of contents are now automatically wrapped when they exceed the width of the page.
- The Developer portal sidebar now supports a new configuration option -
selectFirstItemOnExpand- to control the behavior of group items. When this option is set totrue, selecting the group name in the sidebar automatically activates the first item in the group. When using this option, you must not add thepageoption to the samegroup.
Resolved an issue with circular references preventing the
MenuItemoverride from importing the originalMenuItemand decorating it.Upgraded the
@redocly/reference-docslibrary to version1.5.5.
- Upgraded the
@redocly/reference-docslibrary to version1.5.4. Check the Reference docs changelog for details on what's new in that version.
Resolved an issue with the login button using an invalid
pathPrefixwhich affected the login page URL in build previews.Inline code in MD(X) pages now wraps properly and no longer exceeds the width of the containing element.
If the content on your portal is protected behind a login, you can now set up the login component without having to implement custom overrides. Define the settings for your login button and menu in the siteConfig.yaml file, then customize the user avatar in the
components > loginsection of the theme.ts file. Note that the login component is disabled by default, and that it requires you to configure login and authentication settings for the portal.The portal now supports a login page in local development mode, making it easier to simulate the login process for debugging purposes.
The following Apigee page components are now built into the portal and can be imported from
@redocly/developer-portal/apigee:AppPageAppsPageCreateAppPage
Check the developer portal starter repository for an example, and refer to our Apigee integration documentation to understand how Apigee works with Redocly Developer portal.
You can now integrate Google Global Site Tag into your developer portal. When configured, this integration works only in production, not in local development mode. Check our siteConfig.yaml documentation for instructions on how to set it up.
Developer portal now supports overriding the global
Appwrapper to set a custom global context. The override should be created as a new file_override/App.tsx, and the portal must be restarted after saving the file to apply the changes.The
usePageDatahelper can now returnpageId(an internal portal page ID) and the pagefrontmatterobject (if applicable).
- The package
@redocly/uiis now deprecated. From this version forward, use@redocly/developer-portal/uiinstead.
Resolved an issue with old versions of the
yamlmodule that could happen when upgrading the portal without removing the.lockfile.Resolved an issue with builds breaking for portals that use the
JsonSchemacomponent after upgrading to the1.0.0-beta.139version.Implemented the improvements from Reference docs 1.5.1.
- We have improved the organization of the main portal configuration file,
siteConfig.yaml. All analytics integrations are now configured under the top-levelanalyticskey. Compare the old and the new configuration syntax:
- ga:
- trackingId: your-google-analytics-tracking-id
- googleTagManager:
- id: your-google-tag-manager-id
-
+ analytics:
+ ga:
+ trackingId: your-google-analytics-tracking-id
+ googleTagManager:
+ id: your-google-tag-manager-id
+Although the old configuration syntax still works, it displays warnings in the log, so we recommend switching to the new one.
- You can now integrate FullStory analytics into your developer portal. When configured, this integration works only in production, not in local development mode. Set it up in your
siteConfig.yamlfile like in the following example:
analytics:
fullstory:
fs_org: YOUR_ORG_ID- The
headerIconoption in thesiteConfig.yamlconfiguration file has been deprecated. Uselogoinstead to set the path to your portal logo.
- Resolved an issue with the
hideInfoSection: truenot working in integrated Reference docs pages.
Rich metadata images are now supported in the front matter of MD(X) pages. Add
image: /path/to/image-fileto the front matter of a page to set up its preview image. This image is displayed when sharing the link to the page on social media.You can now set the contents of the
<meta name="keywords">tag in your portal. Provide the keywords as a comma-separated list, e.g.keywords: documentation, api, openapiin themetasection of thesiteConfig.yamlfile. You can also override the site-wide keywords and set them in the front matter of each individual MD(X) page.At last, the developer portal theme lets you style buttons. You can change the font weight and font family of the button text, control button shadowing and hover behavior, and set the border radius for the button element. All these options should be set in the
components > buttonssection of yourtheme.tsfile. Additionally, we have improved the overall default appearance of buttons in the portal, and made their font sizes and shadows more consistent.
- Resolved an issue related to Next/Back buttons when RBAC is enabled in the portal.
Broken release.
- Resolved an issue with the wrong
core-jsimport that was crashing the tests for some of our customers.
To improve the navigation in your developer portal, you can now enable the "Back to" button on MD(X) pages. To enable the button site-wide, for all pages at once, add
showPrevButton: trueto thesiteConfig.yamlfile. Alternatively, enable it only on specific pages by addingshowPrevButton: trueto the page front matter.If you reference any files (such as images or Markdown pages) in the front matter of your MD(X) files, those files are now copied to the
staticfolder in the portal. References to those files are automatically replaced by their destination links.
- Resolved an issue with
requireimages caused by the upgrade to Gatsby v3.
- The portal can now use top-level context to pass the current API definition down to components. This allows users to import the context (as
import {usePageData} from '@redocly/developer-portal/ui') and use it in their own custom components (asconst {rawApiDefinition} = usePageData();).
Removed the old version of the API Overview page in integrated Reference docs and implemented support for the new one.
After logout, the portal now redirects to a path with a trailing slash.
Definition IDs with dashes (e.g.
api-main) now work properly with components that requiredefinitionId, such as OpenApiExample or OpenApiRequestBody.Resolved an issue where long group sublabels in drilldown sidebar style would overflow the sidebar width.
Resolved an issue with the portal navbar not taking the full screen width and displaying gaps on the sides.
Resolved an issue with incorrect paths for the Reference docs license key on Windows.
Broken release.
- Resolved an issue with RBAC where menu item permissions in the sidebar were lost for pages added using the
/*pattern.
- We have migrated the Developer portal to Gatsby v3, updated all outdated dependencies, and resolved security warnings.
To upgrade your portal to this version, first remove yarn.lock, then run yarn clean, followed by yarn install.
- Checkboxes for oAuth2 scopes in the clientCredentials flow are now properly rendered in the Reference docs Try it console.
Resolved an issue with the search index not working for partial operation path fragments (e.g. in
user/findById, thefindByIdpart was not searchable).Improved the custom login functionality for multiple identity providers. This is supported only in developer portals hosted on-premise.
Resolved an issue with the sidebar and the Try it console scrolling under the navigation bar in some cases.
Resolved an issue with auth section links pointing to an invalid URL when using the
index.page.yamlfile in the root of the portal.
Resolved an issue with the Reference docs version switcher not working correctly for operations without a tag and the overview page.
OAS definitions errors are now displayed in the terminal output.
Improved page scrolling handlers to optimize performance.
- The
rightPanel > widththeming option can now accept the CSScalcfunction as a value.
The
rightPanel > widththeming option now supports media query values, allowing you to customize it depending on the screen size (example:rightPanel: { width: { medium: '40%', large: '800px'}}).The
typography > linkssection of the Developer portal theme now lets you customize thetextDecorationvalue.The
pageIdis now passed to custom Markdown template properties.
- Pinned the version of the
informedlibrary to prevent an infinite loop when opening the Try it console in Reference docs.
- Resolved an issue with RBAC not working for portals hosted in Workflows when the
authsection was omitted from thesiteConfig.yamlfile.
- You can now customize the width and padding of the main content wrapper (the area containing the text from your MD(X) pages). This is done by modifying the values in the
contentWrappersection of your portaltheme.tsfile:
components:
contentWrapper: {
maxWidth: '910px',
paddingHorizontal: '0',
paddingVertical: '40px',
},- Resolved an issue with the incorrect default
maxWidthvalue of the main content wrapper element.
- You can now customize the values for
marginTop,marginBottom,marginLeftandmarginRightin the developer portaltheme.tsfile for all heading levels (H1 to H6). Here is an example for H2:
heading2: {
fontSize: '1.50em',
fontWeight: '600',
color: '#000000',
capitalize: false,
marginTop: '1.25em',
marginBottom: '0.8em',
},
- The developer portal now allows you to define the value of theming options as a breakpoints object. When configured in this way, theming options are used according to the breakpoints specified in the theme, ensuring your portal looks great at any screen size.
Here is an example excerpt from the theme.ts file showing how to define a breakpoints object for typography.fontSize:
breakpoints: {
small: '320px',
medium: '720px',
large: '1280px',
},
typography: {
fontSize: { _: '36px', small: '42px', medium: '52px', large: '60px' },
lineHeight: '1.6'
}In this example, the font size of 42 px is used only on small screen sizes. Values configured as strings (like lineHeight in the example) are used on all screen sizes. The special breakpoint _ cannot be manually set in the breakpoints section of the theme, but you should use it in all breakpoints objects. It defines the value for the smallest screen sizes (0 to "small"). If you don't specify it, the default theme value is used instead.
The following theming options now support the breakpoints object as the value (in addition to previously supported string values):
typography:
fontFamily,
fontSize,
lineHeight,
code:
fontFamily,
fontSize
headings:
fontFamily,
lineHeight
heading1 to heading6:
fontFamily,
fontSize,
lineHeight,
marginBottom,
marginLeft,
marginRight,
marginTop,
marginHorizontal,
marginVertical
rightPanelHeading:
fontFamily,
fontSize,
lineHeight
fieldName:
fontFamily,
fontSize,
lineHeight
schema:
constraints:
fontFamily,
fontSize,
lineHeight
examples:
fontFamily,
fontSize,
lineHeight
sidebar:
fontFamily
codeBlock:
tokens:
default:
fontFamily,
fontSize,
lineHeight- A new theming option
showAtBreakpointis supported in therightPanelsection of thetheme.tsfile. Use this option to control the starting screen size at which the right panel is visible in Reference docs pages. Its value must be a string, and it must match one of the breakpoints defined in the theme.
Example
rightPanel: {
backgroundColor: 'red',
textColor: '#000000',
showAtBreakpoint: 'medium'
}301 redirects are now supported and are functional in build previews for developer portals hosted in Redocly Workflows.
Removed the linear gradient when the
bgImageproperty is used with the Jumbotron component.
A new type of alert (or admonition) called
infois now supported in Markdown files. Read more about using admonitions.You can now customize all types of alerts directly in the developer portal theme. New theming options cover font and color changes, including the option to set custom icons for alert boxes.
Speaking of custom icons, you can now change the default icon used in the search bar (when search is enabled in your portal). Override the default icon with another one of your choice, or just modify its color. These options must be set in the developer portal theme.
Blockquotes now support additional styling options in the developer portal theme.
Internal links are now handled client-side and no longer trigger a full page reload.
Resolved an issue with the
logouthelper function redirecting to a wrong location when the portal was built with--prefix-paths.Text formatted as inline code now properly supports line breaks and no longer overflows the page width.
Removed excessive top margin from the content wrapper.
The icons in alert boxes (also known as admonitions) are now centered in relation to the text, and their appearance has been improved to make them stand out.
You can now disable Sharp-based image optimization for your developer portal by setting
disableImagesOptimization: truein thesiteConfig.yamlfile. Sharp is now an optional dependency in the portal installation, so if it fails to install for any reason, the portal continues to work.Image optimization is now disabled by default in portal development mode. To enable it in your local development server:
either add the
--with-images-optimizationflag to thestartcommand inpackage.json,or run the server with
yarn start --with-images-optimization.
- A new front matter option
redirectFromis now supported in MD(X) pages. Use this option to define a list of one or more URLs. This option creates meta-refresh redirects from all listed URLs to your page when building the portal.
- Resolved several minor issues with search indexing for integrated Reference docs with pagination set to
itemorsection.
- Markdown files now support simpler, more convenient syntax for admonitions (warnings, notes, tips...). You can use these admonition types:
info,success,warning,danger,attention- read the documentation for more details. Here's a comparison of the old and the new syntax:
- <div class="warning"><b>Optional title</b>
-
- Some warning text
-
- </div>
+ :::warning Optional title
+
+ Some warning text
+
+ :::- The search functionality now works for integrated Reference docs when pagination is set to
itemorsection.
New, simplified pagination options for Reference docs are now supported in the Developer portal. The behavior and settings for paginated Reference docs in the portal are now consistent with that of standalone Reference docs. Find more details on new defaults and how to adjust them in the Migration guide section.
A new configuration option
hideInfoDescriptionis now supported in.page.yamlfiles for finer control over the integrated Reference docs content.
When integrating Reference docs into your portal, do not use the following options in
.page.yamlfile(s), as they are no longer supported:expandincludeSectionsshowInfo
When declaring the type for integrated Reference docs in
.page.yamlfile(s), set it astype: reference-docs. Setting it astype: redocis no longer supported.
After upgrading to Developer portal 1.0.0-beta.117, you may notice some changes in your integrated Reference docs. You may also need to modify the configuration options in your .page.yaml files.
Here's a list of changes and new defaults you may want to adjust:
Build logs show warnings for the
type: redocvalue in your.page.yamlfile(s). Change it totype: reference-docs.The
showInfooption is no longer supported in.page.yamlfiles. The functionality ofshowInfo: trueis now the default, so you can remove it from.page.yaml. To replace the functionality ofshowInfo: false, addhideInfoSection: trueundersettings.
type: reference-docs
definitionId: example
settings:
hideInfoSection: trueBy default, your integrated Reference docs now have an API overview page like the standalone Reference docs, with basic information about the API and the Download button. This page has its own menu item in the sidebar, and uses the
info.titlevalue from the API definition as the default item name. To set a custom menu item name, use thelabeloption in the.page.yamlfile. To hide the Download button on the API overview page, addhideDownloadButton: trueundersettings. To hide the entire API overview page and its menu item in the sidebar, addhideInfoSection: trueundersettings.The
expandoption is no longer supported in.page.yamlfiles. To replace the functionality ofexpand: false, addpagination: noneundersettingsin your.page.yamlfile, then include that.page.yamlfile insidebars.yamlas follows:
exampleSidebar:
- page: openapi/reference.page.yaml/*
- page: other-example-page.mdTo replace the functionality of expand: true, add either pagination: item or pagination: section under settings˙.
The
includeSectionsoption is no longer supported in.page.yamlfiles. To replace the functionality ofincludeSections: false, addhideInfoDescription: trueundersettings. The functionality ofincludeSections: trueis now the default, so you can remove it from.page.yaml.Markdown sections from your API definition
info.descriptionare now displayed by default. To hide them, addhideInfoDescription: trueundersettings. This does not hide the entireinfosection.The authentication section is added by default to your
info.descriptionsections. To hide it, addnoAutoAuth: trueundersettings.
In summary, consider adding these settings to hide content that's now visible by default:
settings:
hideInfoSection: true
hideInfoDescription: true
hideDownloadButton: true
noAutoAuth: true- Implemented the set of improvements from Reference docs 1.3.19.
- New theming options for item spacing are now supported in the sidebar.
- The version switcher sticks to the the top of the sidebar.
- Fixed group expand/collapse behavior for specific cases.
- Fixed inconsistent spacing when groups and pages are at the same level.
In addition to previously supported relative links (
../guides/example.md), your links to MD(X) files can now be absolute (/guides/example.md) from the root of the Developer portal. This gives you more freedom when linking your content.The version switcher element for quick navigation between multiple API documentation versions is now supported in the Developer portal. To enable it for integrated Reference docs in your portal, list the
versionsyou want to display in the.page.yamlfile(s). Read more in the reference docs integration.
Broken releases.
- Redocly Developer portal now sports a freshly redesigned sidebar. It's not just about the looks, either - several sidebar theming and configuration options are now available. For example, you can add a custom icon and custom description text to sidebar groups when using the
drilldownsidebar style. A new type of separator - horizontal divider line - is also supported, and can be added to the sidebar asseparatorLine: true. New theming options make it possible to change the sidebar background color, font family and size, separator color, and control the spacing of items. Read more on how to customize the portal sidebar in the documentation.
Updating to this version of Developer portal automatically changes the visual style of your portal sidebar, but it does not change your sidebars.yaml file contents.
To revert to the old sidebar style, you must either downgrade your Developer portal to an older version or override the sidebar. A basic override example is available in the developer portal starter repository.
- Implemented the set of UX improvements to the Try it console from Reference docs 1.3.17.
The Next to navigation button visible at the bottom right of portal pages can now be hidden. You can disable it for the entire developer portal by setting
showNextButtontofalsein thesiteConfig.yamlfile. Alternatively, hide it for each individual page by settingshowNextButton: falsein the front matter of your MD(X) files.Canonical URLs are now supported in the developer portal. To enable this, set a value for
siteUrlin themetasection of yoursiteConfig.yamlfile (for example,siteUrl: 'https://www.example.com'). This value will be used as the base URL for canonical links, andrel="canonical"will be automatically added to the head of all HTML pages in your portal.
A new helper function called
usePathPrefixis now available and can be imported from@redocly/ui.A new front matter option
excludeis now supported on MD and MDX pages. Use it to exclude an entire page from the portal build by addingexclude: trueto the page front matter.The
WideTilecomponent now supports themaxWidthproperty. You can configure the property as a percentage or as an exact amount of pixels.
Issues with the Reference docs configuration option
showRightPanelTogglehave been resolved.Tile components now properly support
mailto:links.If your developer portal project contains a top-level
README.mdfile, this file is now excluded from the portal build.When using the
WideTilecomponent that contains an icon, the icon and the content is now aligned to the top of the tile element instead of to the center.
Implemented support for multiple identity providers in the on-premise Docker container. Identity providers can be configured in the
authsection of the siteConfig.yaml file.The
LoginPageLinkcomponent now supports a new property calledidpId. Use it to specify one of the identity providers configured in the siteConfig.yaml file. If you're using React hooks, you can now import the custom hookuseLoginPageUrlfrom@redocly/uiand use it withidpIdlike in the following example:
const loginLink = useLoginPageUrl(idpId);Note that these changes apply only to the on-premise Docker container, not to hosted Developer portals.
- The
allowLoginWithconfiguration option for the on-premise Docker container is now deprecated and should not be used.
Fixed breaking builds after
yarn.lockandnode_modulesare deleted.Fixed the
--relative-pathsargument by using path prefixes from an environment variable.Fixed incorrect path resolution of reusable Markdown snippets.
Broken release.
- Pinned
mobxdependency to prevent crashes when upgrading.
The search index no longer crashes when page names start with
_.Resolved a cryptic JavaScript error when the portal failed to load an OpenAPI definition.
Improved real-time reloading when the sidebar state changes to
expanded.
Fixed crashing when reusable Markdown snippets are embedded in MDX.
Added a warning that snippets are not supported in MDX.
Removed bad
#undefinedhash in some links.
- Redocly now supports single-source authoring and content reuse with Markdown snippets. Create "chunks" of text, save them as Markdown files in your developer portal project, and embed them into other pages across the portal.
Implemented support for
pathPrefixin the RBAC feature.The HTTP scheme name (e.g. Bearer) is now capitalized in code samples.
- Users can now override defaults to customize
SearchInputandSearchResultscomponents.
- Removed many incorrect warnings that were cluttering the console output.
Resolved an issue with mermaid diagrams overflowing the page size.
Resolved a HTML-related nesting issue by rendering
ThinTileas adivif it doesn't have thetoproperty.Lint problems are now ignored for registry downloads.
- Developer portal now supports auto-generated C# and Python code samples in embedded API reference documentation.
Implemented support for the correct default RBAC permission.
The mobile view button for expanding the sidebar menu has been temporarily disabled because of a bug in the full non-paginated reference docs page.
A new front matter configuration option is available -
excludeFromSearch. When you addexcludeFromSearch: trueto the front matter of a Markdown page, the page is excluded from the search index and is not accessible from the search results.Implemented support for
matchPathin MDX pages. This functionality is required for advanced client routes and for the upcoming Apigee portal integration.
Hash fragments (named anchors) can now be used in relative links to MD and MDX pages; for example
[link](./file.md#section-id).Previously, OAS 2 API definitions could be imported only as files from the local filesystem. Now they can be imported from URLs, and they work with registry snapshot URLs (including the Logs > Snapshots > Get Snapshot option).
Resolved a minor styling issue with the position of anchor link icons when targeting an HTML heading.
Broken release.
It is now possible to customize the entire sidebar menu. Check the developer portal starter repository for an example of how to change the sidebar style.
By popular demand, links in the navigation bar can now have custom icons. To add a custom icon for an item, provide the path to the icon image as the value of the new
iconfield in thenavsection of thesiteConfig.yamlfile. An example is available in the developer portal starter repository.
- Improved the look of parameters with multiple examples in Reference docs.
- Implemented support for using API reference docs as the index page of the developer portal. This can be achieved either by renaming the reference docs page to
index.page.yamlor by settingpath: "/"in the corresponding.page.yamlfile. Buttoncomponents without atolink are now rendered as<button>instead of as<a>.- Portal no longer crashes when the
siteConfig.yamlfile contains an invalid page item innav.
- Sidebar items can now be customized independently of the developer portal theme. Check the developer portal starter repository for an example of how to style the sidebar items.
A new CLI option
--ignore-openapi-errorsis now supported. When this option is used, the portal build does not fail if validation errors are found in API definition files.Implemented a new helper React hook called
useAPICatalogin@redocly/ui. It returns a list of all API definitions in the developer portal project (plus some metadata), and can be used to create API catalog pages.
- Internal release without changes.
- Implemented support for the RBAC (Role-based access control) feature. With RBAC, you can define permissions for accessing specific parts of your developer portal, and assign those permissions to different types of users (roles). This feature is available only to Enterprise customers, and only if the developer portal is hosted on-premise using Docker.
- Fixed the style for code blocks inside headings.
- The
siteConfig.yamlfile now supports linking to external API definition files by using$refin theoasDefinitionssection.
- Resolved an issue with alert content rendering when content was passed as React children.
- Minor TypeScript type fixes been implemented.
- The Alert UI component now supports nested content for all alert variants. Nested content is added to an alert using the
childrenproperty.
- Properly applied the fix for broken code highlighting on initial page load (issue carried over from previous release).
- All page links on the portal now use lowercase letters. Page links that previously contained uppercase letters are automatically transformed to all lowercase letters (for example,
./developer-portal/Getting-Started.mdbecomes/developer-portal/getting-started/). As a consequence, some links may break after updating to this version of the Developer portal. - When adding pages to the portal using the
/*"spread" pattern to include all files from a path, the pages are now grouped by folder in the navigation sidebar.
- Resolved an issue with broken code highlighting on initial page load.
- Implemented a performance fix in search-indexer for API definitions that use deep-nested
oneOf. This change potentially resolves the RAM overflow issue reported by some customers. - Fixed the 401 error for manifest.json file when using basic authentication.
- Code samples in Reference docs can now be automatically generated for curl, JavaScript, and Node.js. This feature can be enabled for on-premise Developer portal deployments by editing the
.page.yamlconfiguration file.
- Reduced the clutter in the browser log output.
- Upgraded to the latest version of reference-docs. This version introduces support for CORS Proxy configuration, allowing more control over requests sent from the "Try It" API console.
- New options for styling the portal sidebar are now available; namely:
sidebar.textColor,sidebar.activeTextColor, andsidebar.activeBgColor.
- The layout of API reference docs is no longer broken on small screen sizes in Firefox. GitHub issue reference
- Styled components can now be used for styling
ThinTile,WideTileandAlert. - Custom queries are properly extracted from MDX files with Windows-style line endings.
colors.<color>.contrastTextcan now be used for theAlerttext color, where<color>iswarning,success,error, orinfo.
- Allow running development server on GitHub Codespaces.
- Upgrade reference-docs to
v1.1.5. - Copy auth metadata to artifacts folder (for on-prem auth-server).
- Reduced clutter in the log output.
- Resolved an issue with redirecting to the developer portal home page after the user logs out.
- Exported the
setSecurityDetailshelper.
- Fix
requireLogininfinite reloading.
- Fix some utility functions that were not exported.
- Export helpers for anonymous login.
- Fix JsonSchema style issue.
- Add new side menu style:
drilldown.
- Add new OpenAPI-powered components:
OpenApiRequestBody,OpenApiExample,JsonSchema.
- Fix non-
expandedreference docs broken build.
- Renamed
APIResponsetoOpenApiResponse.
- Use remote rendering for mermaid diagrams.
- Support for IdP issued tokens for Redocly Workflows OIDC integration.
Broken release.
- Fixed badge label for webhooks (with
x-webhooksusage).
- Upgrade to the latest Redocly
reference-docs:x-webhookssupport- accessibility features
- Fixed broken pages with spread
/*.
- Proper error message for missing pages with spread
/*instead of crash.
- Export some auth helpers:
useProxiedFetch,getUserJwt,getUserId.
- Fixed WideTile icon margins.
- Adjusted default style of Tiles.
Add new style properties to ThinTile and WideTile.
Add
colors.navbar.gradienttoggle to thetheme.ts.Support code snippet title
Example usage
Syntax:
```js JavaScript Example console.log('Hello, JS'); ``` ```python Python Example print('Hello, python'); ```Result:
console.log('Hello, JS');print('Hello, python');Upgrade
mermaidto^8.6.0(support auto-wrapping and newlines).Add option
tocMaxDepthto limit the number of nested levels (globally insiteConfig.yamlor in front matter).Add option
disableLastModifiedto hide last modified label (globally insiteConfig.yamlor in front matter).
- Fix local css loading on Windows.
- Fix inconsistent box shadow for thin tile.
- Fix site meta image.
- Support relative paths starting with
./in sidebar.yaml. - Support
external: trueto show external site icon for sidebar menu items. - Fix
"Next to"button for groups with page.