Reference docs changelog

Reference docs 2.0.4 (2021-07-20)

Features

• You can now use the new configuration option generatedPayloadSamplesMaxDepth to control the maximum number of schema levels displayed in automatically generated payload samples.

Fixes

• Added support for x-examples and x-example specification extensions in OAS 2.0 documents.

Reference docs 2.0 [2.0.3] (2021-07-08)

Features

• This major release of Reference docs brings a complete visual overhaul to your API reference docs! Enjoy the new, clean and modern look with many usability and performance improvements under the hood.

You'll notice the following changes:

• Sticky language selection in code sample tabs persists between page reloads and across all operations on the page.
• Deep links let you quickly and easily access parameters and properties in response/request schemas.
• OpenAPI 3.1 is now supported, and Reference docs can build API documentation from your API definitions that use it.
• When using the search functionality, the results are now more readable and displayed in a centered floating window.
• The two buttons in the upper right corner let you control the layout of the page. Select Hide samples to remove the right panel with code samples and center the middle panel contents. Select Change layout to move the contents of the right panel into the middle panel.
• All request and response sections in middle and right panels are now expandable, and can be expanded/collapsed independently of one another.
• The Try it button is now smaller and fits right next to the operation in the right panel. The operation section can expand to show the list of servers.
• You can limit how many code sample tabs to show by default in the right panel with the samplesTabsMaxCount configuration option. The rest of the tabs are automatically folded into a "show more" menu.
• Models with oneOf, anyOf, allOf are now displayed in tabs within the middle panel.

For the full list of changes and upgrade instructions, make sure to read the migration guide.

• You can now use custom hooks to inject additional components and modify or override the default Reference docs layout. The following new hooks are supported: beforeOperation, afterOperation, beforeOperationSummary, afterOperationSummary, replaceTryItAuthPanel.

Fixes

• Resolved a number of performance and usability issues as part of the redesign.
• Resolved an issue in the Try it console where the password field content overlapped the show/hide button.
• Minor improvements to buttons.
• Fixed the wrong color of the operation path.
• Improved padding between panels when using the showDarkRightPanel theming option.

1.5.14 (2021-07-02)

Fixes

• Resolved an issue where optional request parameters were included in requests sent from the Try it console even when their values were empty.

1.5.13 (2021-06-22)

Features

• A new specification extension x-defaultClientId is now supported by Reference docs. Use it in your OpenAPI documents to preset the default clientId value in relevant security definitions; for example:

type: oauth2
flows:
  implicit:
    x-defaultClientId: example123
    authorizationUrl: https://example.com/api/oauth/dialog
    scopes:
      write:pets: modify pets in your account
      read:pets: read your pets

Fixes

• Resolved an issue that prevented the Try it console from functioning properly.

1.5.12 (2021-06-21)

Fixes

• Resolved an issue with custom favicon settings that were not applied (the favicon was not visible for the API reference documentation page). Additionally, you can now set a custom favicon when using the Reference docs CLI tool (for example, reference-docs build openapi.yaml favicon=image.png).

1.5.11 (2021-06-16)

Fixes

• Resolved an issue with the Try it console where an error was displayed in the Auth tab after users corrected their previously incorrect credentials.
• Text in the Payload section for response and request samples now correctly applies typography theme settings and uses the font configured in theme.typography.code.fontFamily.

1.5.10 (2021-06-16)

Fixes

• Resolved an issue that caused a crash when using the Reference docs library with Jest unit tests and a proxy-based mock.

1.5.9 (2021-06-15)

Fixes

• Resolved an issue that caused a crash when using the Reference docs library with Jest unit tests without a CSS preprocessor.

1.5.8 (2021-06-10)

Fixes

• Resolved a compatibility issue with Webpack 5 so that it no longer requires a special loader when used with Redocly libraries.

1.5.7 (2021-06-01)

Fixes

• Resolved an issue with incorrect width of the schema element in the middle panel.

1.5.6 (2021-06-01)

Features

• When documenting enum values in your OpenAPI definition, you can now add an individual description for each of the values by using the x-enumDescriptions object. Reference docs will display the enum values and their descriptions as a table in the schema, in the same order as they are listed in the API definition. The table contents are partially hidden and can be expanded on click if there are more enum values than specified by the maxDisplayedEnumValues configuration option.

The following example shows how to add descriptions to enum values in your OpenAPI definition:

user_status:
  type: string
  title: Status indicator
  description: "Indicates the status of the user account. This status is visible only internally to account administrators."
  x-enumDescriptions:
    ON: User account activated
    OFF: User account deactivated
    BAN: User account banned permanently
    CAT: User is a cat

1.5.5 (2021-05-24)

Fixes

• Schemas can now be horizontally scrolled when their contents overflow the width of the middle panel.

1.5.4 (2021-05-20)

Features

• You can now replace the default "Username" and "Password" label text in the Try it authorization section with any custom text. To do that, use the following options in your Reference docs configuration file(s):

labels:
  tryItAuthBasicUsername: 'Your custom username label'
  tryItAuthBasicPassword: 'Your custom password label'

1.5.3 (2021-05-20)

Fixes

• Resolved an issue with the Try it console which prevented long request bodies from being displayed.

1.5.2 (2021-05-17)

Fixes

• Resolved an issue with the Try it console sending the Accept header for wrong media types in requests.

1.5.1 (2021-05-11)

Fixes

• Authorizations are now supported in labels and can be overridden in custom components.

1.5.0 (2021-05-06)

Features

• A new configuration option schemaExpansionLevel lets you automatically expand schemas in your Reference docs. Set it to all to expand all schemas regardless of their level, or set it to a number to expand schemas up to the specified level. For example, schemaExpansionLevel: 3 expands schemas up to three levels deep. The default value is 0, meaning no schemas are expanded automatically.
• The reference-docs CLI tool now supports an option called --html-template-variables. Use it to pass custom dynamic values to your Reference docs HTML template at build time. For example, if your HTML template contains {{{CUSTOM_VARIABLE}}}, you can run npx @redocly/reference-docs build openapi.yaml --html-template-variables '{"CUSTOM_VARIABLE": "Redocly"}' to set its value to "Redocly". Note that the following variable names are reserved: redocBody, redocHTML, title, redocHead.

1.4.0 (2021-04-29)

Features

• This major release of Reference docs marks an important point for users who rely on the Reference docs package. The @redocly/reference-docs-lib package is now deprecated. For all use cases, you should use only the @redocly/reference-docs package (as the CLI tool and the React library).

Fixes

• Resolved an issue where items for object query parameters were not displayed in the Try it console.

1.3.27 (2021-04-12)

Features

• Improved path parameter handling in auto-generated code samples.

Fixes

• Checkboxes for oAuth2 scopes in the clientCredentials flow are now properly rendered in the Try it console.

1.3.26 (2021-03-30)

Fixes

• Resolved an issue with Reference docs crashing when operationId was not defined for x-webhooks.
• Resolved an issue that affected the required parameter label position and caused extra white spaces in Reference docs labels.

1.3.25 (2021-03-30)

Broken release.

1.3.24 (2021-03-30)

Features

• The rightPanel > width theming option now supports media query values, allowing you to customize it depending on the screen size (example: rightPanel: { width: { medium: '40%', large: '800px'}}).

Fixes

• Pinned the version of the informed library to prevent an infinite loop when opening the Try it console.
• Long multiline examples/enum values wrap now and do not overflow the parent container.

1.3.23 (2021-03-26)

Fixes

• Resolved an issue with incorrect width of the Try it console.

1.3.22 (2021-03-26)

Fixes

• Resolved an issue with escaping curly brackets in curl code samples. The fix from Reference docs 1.3.20 is now properly implemented.
• Pinned the versions for Redocly dependencies redoc-int and vscode-json-languageservice.

1.3.21 (2021-03-25)

Fixes

• Reverted the curly brackets fix implemented in the previous version.

1.3.20 (2021-03-25)

Fixes

• Implemented several corrections for imports in auto-generated Java code samples.
• Resolved an issue with the missing JSON library import in auto-generated Java code samples.
• Curly brackets in curl code samples are no longer automatically escaped to allow representing variables as a template or a placeholder in the code sample.

1.3.19 (2021-03-16)

Fixes

• Resolved an issue with pagination: item and pagination: section not working when an operation had the # symbol in its operationId.
• The Try It console will now send the correct payload format when using the application/x-www-form-urlencoded content type.
• Resolved an issue with path parameters not being replaced by user-provided values in the Try It console.

1.3.18 (2021-03-05)

Features

• Simplified pagination settings are now supported in Reference docs. To configure pagination for your Reference docs, add the pagination key to the referenceDocs section of your .redocly.yaml configuration file.

The pagination key can be set to any of the following values: none (all content is rendered on a single long page), section (each tag with a set of associated operations is rendered as a separate page), and item (each tag and operation items are rendered on separate pages). The default value is none.

Deprecated

• The following configuration options for Reference docs have been deprecated, and their functionality superseded by the new pagination option. These options are still supported in .redocly.yaml configuration file(s), but the build logs will show warnings if you continue using them. We strongly recommend adjusting your configuration files to use the new pagination option.

layout.scope = all | section | item

layout.markdownItemsScope = all | section

layout.showTag = true | false

layout.showInfoOnEachPage = true | false

routingStrategy = browser | hash

• The default pagination behavior has changed for the following items, and it's no longer configurable:

  • The tag description will not be displayed on each operation page (previously controlled by layout.showTag = false)
  • Contents of the info object will not be shown on each page (previously controlled by layout.showInfoOnEachPage = false)
  • Markdown items from the info object will not be paginated, and will always be displayed on a single page

1.3.17 (2021-03-04)

Features

• The Try it API console UX has been improved by allowing users to send requests even if the payload is invalid. Additionally, payloads with $refs schemas are now properly supported in the Try it console.

1.3.16 (2021-02-26)

Fixes

• Resolved an issue with multi-version URLs for path-prefixed docs.
• Path-prefixed docs output now works with URLs that don't end with a trailing slash.

1.3.15 (2021-02-16)

Features

• Hostnames ending with .localhost are now supported when using Reference docs on-premise (running a local development server).
• Reference docs CLI now supports the --gzip flag that outputs GZIP-compressed files directly when bundling your API definitions.

1.3.14 (2021-02-15)

Fixes

• Resolved an issue with a false-positive "Recursive" label being displayed for parameters when using some combination of allOf and oneOf.
• The request payload body in the Try It console was not visible until the user clicked in the console area.

1.3.12 (2021-02-02)

Fixes

• Resolved an issue with the "Try it" console crashing for API definitions without security schemes.

1.3.11 (2021-01-31)

Fixes

• The menu toggle button in mobile view is now functional again. Reference docs in Workflows must be rebuilt for this change to take effect.
• Implemented the latest fixes from Redoc to resolve crashes on multiple examples in the parameter object and on code highlights for boolean or number values in examples.

1.3.10 (2021-01-25)

Fixes

• The HTTP scheme name (e.g. Bearer) is now capitalized in code samples.

1.3.9 (2021-01-14)

Fixes

• Upgraded internal dependencies.
• Improved support for HTTP Bearer scheme.
• Switched to enableStaticRendering instead of the deprecated useStaticRendering.

1.3.7 (2020-12-16)

Features

• Reference docs now support auto-generated C# and Python code samples.

Fixes

• Resolved a number of typings and MobX observables issues.
• Fixed default indentation for generated code samples.
• Resolved an issue with broken Node.js and JavaScript code samples.
• Resolved an issue with Basic Authentication in Python code samples.

1.3.6 (2020-12-01)

Features

• The "Try it" button has moved to a new place.

Fixes

• Resolved an issue with failing examples that had empty headers.
• Deprecated specs in favor of definitions.
• Fixed an issue with empty headers.

1.3.5 (2020-11-15)

Fixes

• Fixed a memory overflow issue on some complicated definitions (with combinatorial explosion pattern). This change has been propagated to Redocly Workflows.

1.3.4 (2020-11-11)

Fixes

• Upgraded some internal dependencies.
• Resolved mime-type issues in code samples and issues with OAuth2 clientCredentials with empty scopes.
• Resolved an issue with hash history removing page path on scroll.

1.3.3 (2020-11-05)

Features

• Implemented improvements for handling OAuth2.

1.3.2 (2020-11-02)

Fixes

• Removed console.log.

1.3.1 (2020-10-29)

Fixes

• Fixed TypeScript emit issues.

1.3.0 (2020-10-29)

Features

• Integration with our open-source product Redoc has been upgraded to the latest version to support the hideRequestPayloadSample configuration option.
• Improved Basic Authentication handling.
• Implemented a number of improvements to code samples.
• Converted code samples to async/await.
• Renamed cURL to curl.

Fixes

• Fixed url-encoded and x-www-form-urlencoded.
• Exported setSecurityDetails from standalone package.
• Resolved an issue with multiple auth types.
• Implemented a number of SSR and internal fixes.
• Copied httpsnippet to the repository.

1.2.8 (2020-10-28)

Fixes

• Resolved an issue with broken oneOf when used in recursive schemas.

1.2.7 (2020-10-27)

Features

• Implemented a new theming option called schema.breakFieldNames.

Fixes

• Fixed a crash in next-to button caused by an empty tag.

1.2.6 (2020-10-21)

Fixes

• Resolved an issue with a broken package due to an invalid .npmignore setup.
• Fixed a server-side crash caused by consecutive use of the "Try it" console.

1.2.5 (2020-10-16)

Features

• Implemented the corsProxyUrl configuration parameter.

Fixes

• Fixed a crash caused by empty response.
• Resolved an issue with "Try it" console crashing for API definitions with server variables.
• Implemented URL protocol normalization to automatically add https when a URL starts with //.

1.2.4 (2020-10-06)

Features

• Search is now loading from webworker.

1.2.3 (2020-09-21)

Fixes

• Upgraded openapi-sampler to fix a memory overflow issue.
• Fixed a crash caused by empty auth schema.

1.2.2 (2020-09-14)

Features

• Implemented support for OAuth2 implicit and OpenID Connect.

Fixes

• Crashes will no longer happen on "Try it" blob response.
• Fixed issues that caused crashes and broken server-side rendering when search is disabled.

1.2.1 (2020-10-10)

Features

• Reference docs can now use schema or pointer for the schema component.

Fixes

• Full width panel is now used for components without samples.
• Fixed a crash that would happen when disposing the search store.
• Resolved an issue with wrong console width set on initial load.
• Fixed a broken import in the "Try it" feature.

1.2.0 (2020-08-25)

Reference docs 1.2.0 release!