March was a super productive month at Redocly. Our developer teams delivered many cool features across the board and I am excited to share all of these with you.
Looking back 12 months, we had a very similar March in 2021, so maybe March has a touch of something special going for it.
Let's run through some of the new features, enhancements and documentation-related news from March 2022.
Firstly, we switched over our website and the Redocly app officially to the redocly.com domain! Easy to remember and straight-forward to work with.
Mock server feature
We added the mock server feature to our registry that lets you test your APIs while you design and develop them.
Add your API definitions to the Redocly API registry and enable the mock server for all branches in the API project settings. The API version Overview page displays the mock server link that you can copy and use in any API testing tool to send requests.
For more information on how to use this feature, refer to the mock server quickstart guide.
The mock server is available only to customers on the Pro and Enterprise plans.
Simplified configuration file
The Redocly configuration file is used by multiple Redocly apps (OpenAPI CLI, Workflows, Reference and VS Code extension) to help you control their behavior.
In the latest releases of these apps, we implemented a new format of the configuration file. Our goal was to simplify its usage, improve the integration of Redocly apps, and standardize the way they interpret the configuration file.
To understand what has changed in the configuration file and how to start using the new options, read our migration guide.
Auto detection of labels
If you're using the new
labels section in the Redocly configuration file to assign labels to your APIs, the API registry will detect this and automatically apply the labels to your APIs when you set up your API project.
Keep in mind that you can only assign labels that already exist in your Workflows organization. If you add new labels to the
labels section of the configuration file, it will not create new labels in Workflows, and these labels will be ignored during the API project setup.
SSO for Pro plans
The SSO (Single-Sign On) functionality is now available to users on Pro plans (was only available to Enterprise customers before). SSO accounts count towards the user limit for the organization.
Find out about other fixes and enhancements by visiting the Workflows changelog.
Use example values with Try it console
The Try it console lets you use
example values with object properties to set initial values in the
Reference docs changelog
Here's a link to the entire Reference docs changelog.
Introducing the API catalog
We added the API catalog - a new approach for integrating the developer portal and the API registry. Use the
catalog.yaml file to import assets and integrate multi-version APIs into your portal.
To find out more, refer to the manage your APIs with the API catalog topic.
Edit page button for your portal pages
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 you can link it to a GitHub or a GitLab repository.
You can enable it globally for all pages in the
siteConfig.yaml file, or control it per-page in the front matter.
For more information, refer to the edit page section.
Portal version number
The portal version number is now visible in the developer console to make troubleshooting easier.
Integrate Reference docs directly into the portal
You can integrate Reference docs pages directly into the portal without creating
To achieve this, add your OpenAPI definition file to the portal project and include it into a
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 will have to integrate Reference docs with
.page.yaml files as before.
Refer to our Integrate API reference docs guide to find out how to configure this.
New header for on-page navigation
All table of contents sections now have an "On this page" header. This improves accessibility of the on-page navigation.
Configure sidebars per page
We added support for displaying a sidebar on pages not listed in any
sidebars.yaml file. To do this:
Use the new
sidebaroption in the page front matter, and
Specify which sidebar to display by providing the path to the
sidebars.yamlfile or the sidebar name (if you're using the legacy sidebar configuration with
--- title: Adding sidebar to the page sidebar: training ---
--- title: Adding sidebar to the page sidebar: ../sidebars.yaml ---
If you define 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. For this, 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 will be displayed.
Linting API definitions from the API registry
We added support for linting API definitions from the API registry. To use this feature, either:
--lint-registry-definitionsoption to the portal build command, or
Set up the
Developer portal changelog
Read the entire list of fixes and enhancements on the Developer portal changelog.
New separator option for
We added a
--separator option to the
split command. You can use it to change the separator character instead of whitespace in file names. The default is
_ , which means that after splitting, path file names look like this: "userlogin.yaml", "userlogout", etc.
Renaming the configuration file
You can now name the Redocly config file either
OpenAPI CLI changelog
Read more about OpenAPI CLI fixes and enhancements by visiting the OpenAPI CLI changelog.
To find out more about Redoc CLI fixes and enhancements, see the Redoc changelog.
The technical writing team has been busy adding content for new features and updating existing content to ensure we are filling in the gaps between our product features and docs, and assisting our support team with documenting the frequently asked questions around our products.
Last month, we added:
- Redocly configuration migration guide
- Mock server quickstart
- Manage your APIs with the API catalog
- Integrate API reference docs guide
We also updated a few other topics:
topic with information about the
Added a new
Troubleshootingsection to the sidebar to house migration guides for our products.
Updated all instances of
.redocly.yamlto a more generic "Redocly configuration file" for consistency.
Updates to our open source docs
Along with our core documentation, our new open source technical writer also made some tremendous progress with the OpenAPI CLI docs.
- Created a new openapi-starter guide .
- Updated the quickstart guide with relevant examples.
- Edited the introduction page.
- Simplified the commands page, and
- Simplified the installation page.
The 2022 Google Season of Docs is upon us! Motivated by our last year's success, we are hoping to participate in this year's program and work with technical writers keen on contributing to our open source projects.
To find out how you can contribute, and discuss ideas, read our project proposal.