Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update options for future major release #2646

Merged
merged 8 commits into from
Jan 30, 2025
Merged

docs: update options for future major release #2646

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
38e109e
docs: update options for future major release
AlexVarchuk Jan 14, 2025
2424cc5
docs: move options to deprecated section
AlexVarchuk Jan 15, 2025
3760bd6
docs: improve documantation
AlexVarchuk Jan 15, 2025
4356934
docs: move downloadFileName and downloadDefinitionUrl to deprecated o…
AlexVarchuk Jan 15, 2025
abfb324
chore: add docs
AlexVarchuk Jan 21, 2025
0f1a0eb
chore: fix problem inside documentation
AlexVarchuk Jan 21, 2025
dc11a64
chore: remove html template option
AlexVarchuk Jan 21, 2025
8b58fe9
chore: update docs/config.md
AlexVarchuk Jan 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 0 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -122,10 +122,8 @@ Redoc uses the following [specification extensions](https://redocly.com/docs/api
* [`x-displayName`](docs/redoc-vendor-extensions.md#x-displayname) - specify human-friendly names for the menu categories
* [`x-tagGroups`](docs/redoc-vendor-extensions.md#x-tagGroups) - group tags by categories in the side menu
* [`x-servers`](docs/redoc-vendor-extensions.md#x-servers) - ability to specify different servers for API (backported from OpenAPI 3.0)
* [`x-ignoredHeaderParameters`](docs/redoc-vendor-extensions.md#x-ignoredHeaderParameters) - ability to specify header parameter names to ignore
* [`x-additionalPropertiesName`](docs/redoc-vendor-extensions.md#x-additionalPropertiesName) - ability to supply a descriptive name for the additional property keys
* [`x-summary`](docs/redoc-vendor-extensions.md#x-summary) - for Response object, use as the response button text, with description rendered under the button
* [`x-extendedDiscriminator`](docs/redoc-vendor-extensions.md#x-extendedDiscriminator) - in Schemas, uses this to solve name-clash issues with the standard discriminator
* [`x-explicitMappingOnly`](docs/redoc-vendor-extensions.md#x-explicitMappingOnly) - in Schemas, display a more descriptive property name in objects with additionalProperties when viewing the property list with an object

## Releases
Expand Down
159 changes: 102 additions & 57 deletions docs/config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,111 +26,158 @@

_Default: 3_

### expandDefaultServerVariables

Enables or disables expanding default server variables.
### hideDownloadButtons

### expandResponses
Hides the 'Download' button for saving the API definition source file. **This setting does not make the API definition private**; it just hides the button.

Controls which responses to expand by default. Specify one or more responses by providing their response codes as a comma-separated list without spaces, for example `expandResponses='200,201'`. Special value 'all' expands all responses by default. Be careful: this option can slow down documentation rendering time.
### hideLoading

### expandSingleSchemaField
Hides the loading animation. Does not apply to CLI or Workflows-rendered docs.

Automatically expands the single field in a schema.
### hideSchemaTitles

### hideDownloadButton
Hides the schema title next to to the type.

Hides the 'Download' button for saving the API definition source file. **This setting does not make the API definition private**; it just hides the button.
### jsonSamplesExpandLevel

### hideHostname
Sets the default expand level for JSON payload samples (response and request body). The default value is 2, and the maximum supported value is '+Infinity'. It can also be configured as a string with the special value `all` that expands all levels.

If set to `true`, the protocol and hostname are not shown in the operation definition.
_Default: 2_

### hideLoading
### maxDisplayedEnumValues

Hides the loading animation. Does not apply to CLI or Workflows-rendered docs.
Displays only the specified number of enum values. The remaining values are hidden in an expandable area. If not set, all values are displayed.

### hideRequestPayloadSample
### onlyRequiredInSamples

Hides request payload examples.
Shows only required fields in request samples.

### hideOneOfDescription
### sortRequiredPropsFirst

If set to `true`, the description for `oneOf`/`anyOf` object is not shown in the schema.
Shows required properties in schemas first, ordered in the same order as in the required array.

### hideSchemaPattern
### schemasExpansionLevel

If set to `true`, the pattern is not shown in the schema.
Specifies whether to automatically expand schemas in 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, `schemasExpansionLevel: 3` expands schemas up to three levels deep. The default value is `0`, meaning no schemas are expanded automatically.

### hideSchemaTitles
### scrollYOffset

Hides the schema title next to to the type.
Specifies a vertical scroll-offset.
This setting is useful when there are fixed positioned elements at the top of the page, such as navbars, headers, etc.

### hideSecuritySection
Note that you can specify the `scrollYOffset` value in any of the following ways:
- as a number - a fixed number of pixels to be used as the offset.
- as a CSS selector - the selector of the element to be used for specifying the offset. The distance from the top of the page to the element's bottom is used as the offset.
- a function (advanced) - a getter function. Must return a number representing the offset (in pixels).

Hides the Security panel section.
### showExtensions

### hideSingleRequestSampleTab
Shows specification extensions ('x-' fields). Extensions used by Redoc are ignored. The value can be boolean or an array of strings with names of extensions to display. When used as boolean and set to `true`, all specification extensions are shown.

Hides the request sample tab for requests with only one sample.
### sanitize

### htmlTemplate
AlexVarchuk marked this conversation as resolved.
Show resolved Hide resolved
If set to `true`, the API definition is considered untrusted and all HTML/Markdown is sanitized to prevent XSS.

Sets the path to the optional HTML file used to modify the layout of the reference docs page.
### downloadUrls

### jsonSampleExpandLevel
Set the URLs used to download the OpenAPI description or other documentation related files from the API documentation page.

Sets the default expand level for JSON payload samples (response and request body). The default value is 2, and the maximum supported value is '+Infinity'. It can also be configured as a string with the special value `all` that expands all levels.
### schemaDefinitionsTagName

_Default: 2_
If a value is set, all of the schemas are rendered with the designated tag name. The schemas then render and display in the sidebar navigation (with that associated tag name).

### maxDisplayedEnumValues
### generatedSamplesMaxDepth

Displays only the specified number of enum values. The remaining values are hidden in an expandable area. If not set, all values are displayed.
The generatedSamplesMaxDepth option controls how many schema levels automatically generated for payload samples. The default is 8 which works well for most APIs, but you can adjust it if necessary for your use case.

### menuToggle
### hidePropertiesPrefix

If set to `true`, selecting an expanded item in the sidebar twice collapses it.
In complex data structures or object schemas where properties are nested within parent objects the hidePropertiesPrefix option enables the hiding of parent names for nested properties within the documentation.

_Default: true_

### nativeScrollbars

If set to `true`, the sidebar uses the native scrollbar instead of perfect-scroll. This setting is a scrolling performance optimization for big API definitions.
## Deprecated Functional settings

### onlyRequiredInSamples
### hideDownloadButton

Shows only required fields in request samples.
Hides the 'Download' button for saving the API definition source file. **This setting does not make the API definition private**; it just hides the button.

### pathInMiddlePanel
### downloadFileName

Shows the path link and HTTP verb in the middle panel instead of the right panel.
Sets the filename for the downloaded API definition source file.

### payloadSampleIdx
### downloadDefinitionUrl

If set, the payload sample is inserted at the specified index. If there are `N` payload samples and the value configured here is bigger than `N`, the payload sample is inserted last. Indexes start from 0.
Sets the URL for the downloaded API definition source file.

### requiredPropsFirst

Shows required properties in schemas first, ordered in the same order as in the required array.

### jsonSampleExpandLevel

Sets the default expand level for JSON payload samples (response and request body). The default value is 2, and the maximum supported value is '+Infinity'. It can also be configured as a string with the special value `all` that expands all levels.

_Default: 2_

### schemaExpansionLevel

Specifies whether to automatically expand schemas in 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.

### scrollYOffset

Specifies a vertical scroll-offset.
This setting is useful when there are fixed positioned elements at the top of the page, such as navbars, headers, etc.
### expandDefaultServerVariables

Note that you can specify the `scrollYOffset` value in any of the following ways:
- as a number - a fixed number of pixels to be used as the offset.
- as a CSS selector - the selector of the element to be used for specifying the offset. The distance from the top of the page to the element's bottom is used as the offset.
- a function (advanced) - a getter function. Must return a number representing the offset (in pixels).
Enables or disables expanding default server variables.

### showExtensions
### expandResponses

Shows specification extensions ('x-' fields). Extensions used by Redoc are ignored. The value can be boolean or an array of strings with names of extensions to display. When used as boolean and set to `true`, all specification extensions are shown.
Controls which responses to expand by default. Specify one or more responses by providing their response codes as a comma-separated list without spaces, for example `expandResponses='200,201'`. Special value 'all' expands all responses by default. Be careful: this option can slow down documentation rendering time.

### expandSingleSchemaField

Automatically expands the single field in a schema.

### hideHostname

If set to `true`, the protocol and hostname are not shown in the operation definition.

### hideRequestPayloadSample

Hides request payload examples.

### hideOneOfDescription

If set to `true`, the description for `oneOf`/`anyOf` object is not shown in the schema.

### hideSchemaPattern

If set to `true`, the pattern is not shown in the schema.

### hideSecuritySection

Hides the Security panel section.

### hideSingleRequestSampleTab

Hides the request sample tab for requests with only one sample.

### menuToggle

If set to `true`, selecting an expanded item in the sidebar twice collapses it.

_Default: true_

### nativeScrollbars

If set to `true`, the sidebar uses the native scrollbar instead of perfect-scroll. This setting is a scrolling performance optimization for big API definitions.

### pathInMiddlePanel

Shows the path link and HTTP verb in the middle panel instead of the right panel.

### payloadSampleIdx

If set, the payload sample is inserted at the specified index. If there are `N` payload samples and the value configured here is bigger than `N`, the payload sample is inserted last. Indexes start from 0.

### showObjectSchemaExamples

Expand Down Expand Up @@ -162,12 +209,12 @@

_Default: false_

### untrustedDefinition
### untrustedSpec

If set to `true`, the API definition is considered untrusted and all HTML/Markdown is sanitized to prevent XSS.

## Theme settings

Change styles for the API documentation page **Supported in Redoc CE 2.x**.
AlexVarchuk marked this conversation as resolved.
Show resolved Hide resolved
* `spacing`
* `unit`: 5 # main spacing unit used in autocomputed theme values later
* `sectionHorizontal`: 40 # Horizontal section padding. COMPUTED: spacing.unit * 8
Expand Down Expand Up @@ -248,7 +295,7 @@

### OpenAPI specification extensions

Redoc uses the following [specification extensions](https://redocly.com/docs/api-reference-docs/spec-extensions/):
Redoc uses the following [specification extensions](https://redocly.com/docs-legacy/api-reference-docs/spec-extensions/):

Check warning on line 298 in docs/config.md

View workflow job for this annotation

GitHub Actions / linkcheck

link checker warning 

https://redocly.com/docs-legacy/api-reference-docs/spec-extensions/. 200 - OK
* [`x-logo`](./redoc-vendor-extensions.md#x-logo) - is used to specify API logo
* [`x-traitTag`](./redoc-vendor-extensions.md#x-traittag) - useful for handling out common things like Pagination, Rate-Limits, etc
* [`x-codeSamples`](./redoc-vendor-extensions.md#x-codesamples) - specify operation code samples
Expand All @@ -257,10 +304,8 @@
* [`x-displayName`](./redoc-vendor-extensions.md#x-displayname) - specify human-friendly names for the menu categories
* [`x-tagGroups`](./redoc-vendor-extensions.md#x-taggroups) - group tags by categories in the side menu
* [`x-servers`](./redoc-vendor-extensions.md#x-servers) - ability to specify different servers for API (backported from OpenAPI 3.0)
* [`x-ignoredHeaderParameters`](./redoc-vendor-extensions.md#x-ignoredheaderparameters) - ability to specify header parameter names to ignore
* [`x-additionalPropertiesName`](./redoc-vendor-extensions.md#x-additionalpropertiesname) - ability to supply a descriptive name for the additional property keys
* [`x-summary`](./redoc-vendor-extensions.md#x-summary) - For Response object, use as the response button text, with description rendered under the button
* [`x-extendedDiscriminator`](./redoc-vendor-extensions.md#x-extendeddiscriminator) - In Schemas, uses this to solve name-clash issues with the standard discriminator
* [`x-explicitMappingOnly`](./redoc-vendor-extensions.md#x-explicitmappingonly) - In Schemas, display a more descriptive property name in objects with additionalProperties when viewing the property list with an object


2 changes: 1 addition & 1 deletion docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ theme:
openapi:
disableSearch: true
expandResponses: 200,202
jsonSampleExpandLevel: 1
jsonSamplesExpandLevel: 1

theme:
sidebar:
Expand Down
Loading
Loading