November 2021 updates

November felt like a wrap-up month at Redocly, in the sense that we wrapped up some really big projects and made some nifty UX improvements to our products such as the OpenAPI VS Code extension, Redoc and the Developer portal.

Let's have a quick look at our new features, enhancements and documentation-related news from November 2021.

We are also on a lookout for developers and documentarians at Redocly, so if you are interested in joining a leader in the API design and documentation space, keep reading for more details.


Redocly OpenAPI VS Code extension

After several months of incremental improvements, we're happy to announce a new major release of the Redocly OpenAPI extension for VS Code. For this new version, we focused on improving the usability of the extension, paying special attention to first-time OpenAPI authors and those who prefer a guided approach to writing API definitions.

Here are five reasons to try it today.

API registry

Clearer warnings with API validation

When validating your API definitions, the API registry now shows the exact rule name that generated a warning in the Results output.

Improved cancel subscription form

We value your feedback on all things Redocly, so we improved the Cancel subscription form and added the ability for users to provide cancellation reason as feedback. This will help us better understand the user experience and improve our products.

Configurable access control

Organization owners can now disable the Log in with Redocly account option on the Settings > Access control page if they want to use only SSO login for their organization.

When you configure the access to SSO-only, the login flow will indicate that SSO is required for users trying to log in.

Using wildcards in domain names

When generating new license keys from the Workflows > Settings > On-premise license keys page, you can now use wildcards in domain names.

You can only use one wildcard in each configured domain.

info

This also applies to Reference docs.

Changelog

Find out about other fixes and enhancements by visiting the Workflows changelog.

Workflow features


Reference docs

Support for separators in sidebar

Reference docs now supports two new configuration options - separator and separatorLine for items configured in sidebarLinks.

We've also added support for the corresponding theming option called sidebar > separatorLineColor.

Sending header information with every request

We implemented a new configuration option called sendXUserAgentInTryIt to enable sending the X-User-Agent: Redocly Try it API console header with every request made from the Try it console.

NOTE: Before you can use this, make sure you add X-User-Agent to your Access-Control-Allow-Headers CORS header.

Automatic wrapping of long server URLs

  • Long server URLs in the Try it console now automatically wrap and adjust to the width of their containing element, giving you a clearer look at the full server URL values.
  • The Copy button for server URLs has also been removed to declutter the space.

Support for PKCE for OAuth2

The Try it console now supports PKCE for OAuth2 authorization code flow. To enable it for a specific security definition, add the x-usePkce: true specification extension.

Copy
Copied
components:
  securitySchemes:
    oauth2_auth:
      type: "oauth2"
      flows:
        authorizationCode:
          x-usePkce: true,
          authorizationUrl: "https://example.com/authorize",
          tokenUrl: "https://example.com/token",
          scopes: {
            api: "Grants complete read/write access to the API"

Reference docs changelog

Here's a link to the entire Reference docs changelog.

Reference docs features


Developer portal

Support for Amplitude analytics

You can now use Amplitude analytics with the portal product. For more information on how to configure this, check the Amplitude analytics topic.

Exclude page URLs from sitemap

There may be instances where you don't want certain page links included in your sitemap. You can now use the excludeFromSearch option in the front matter of a page to exclude its URL from sitemap.xml.

Create interactive step-by-step guides

We've added a number of new properties to the OpenApiTryIt component to help you create interactive step-by-step guides.

The new properties are:

  • id (optional)
  • needs (optional)
  • placeholder (optional)
  • serverVariables (optional)

You can also use the new component ExplainStep to add tips and instructions for every step.

For more information, see the Developer portal changelog.

New home for configuration options

We've reorganized configuration options for modifying the <head> contents in your portal. Instead of adding these options to the meta section in siteConfig.yaml or 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 in siteConfig.yaml - a big win for consistency!

Specifically, this affects the following configuration options:

  • description
  • image
  • keywords
  • title
  • lang
  • sitemap in front matter
  • siteUrl in the siteConfig.yaml file, and
  • x-meta specification extension supported in integrated Reference docs pages.
Important

We recommend migrating to this new configuration approach as soon as possible. Although we currently support this, the old approach is now considered deprecated and will display warnings in the portal build log.

Set up JSON-LD parameters

You can now set up JSON-LD parameters for your portal in the siteConfig.yaml file or in the front matter for individual MD(X) pages in the portal.

Developer portal changelog

Read the entire list of fixes and enhancements on the Developer portal changelog.

Developer portal features


OpenAPI CLI and Redoc

OpenAPI CLI changelog

Read more about OpenAPI CLI fixes and enhancements by visiting the OpenAPI CLI changelog.

Redoc changelog

To find out more about Redoc CLI fixes and enhancements, see the Redoc changelog.


Documentation updates

In the last month, our technical writing team spent a good chunk of time attending to customer feedback around documentation.

We added new topics for:


Google Season of Docs 2021 - Completed

The Google Season of Docs for 2021 is now over and we published a case study to highlight our experience with the program.

Redocly hiring documentarians and developers!

We have some rather ambitious plans for 2022, and to help us with that, we are on the lookout for a couple of documentation and developer experience professionals right now.

The technical writing team at Redocly has been pretty busy with some cool docs stuff, and are a great bunch of folks to work with.

If you are keen, or know someone who would be a good fit in the Redocly docs team, have a look at these roles and get in touch:

If you are a developer, we have a total of 33 (yes, you read that right!) developer roles going at the moment.

For a taste of what's involved, check out our Full Stack Developer posting and get in touch with us pronto!

Latest from our blog

How to display schemas separately from operations in API docs?

Answering real questions about how to use OpenAPI to design and describe APIs.

OpenAPI overlays

The OpenAPI overlays proposal is flawed.

How to hide the x-logo

Answering real questions about how to use OpenAPI to design and describe APIs.