diff --git a/docs/config.md b/docs/config.md index b7bc0982..ec839210 100644 --- a/docs/config.md +++ b/docs/config.md @@ -82,10 +82,24 @@ Shows specification extensions ('x-' fields). Extensions used by Redoc are ignor If set to `true`, the API definition is considered untrusted and all HTML/Markdown is sanitized to prevent XSS. -# downloadUrls +### downloadUrls Set the URLs used to download the OpenAPI description or other documentation related files from the API documentation page. +### schemaDefinitionsTagName + +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). + +### generatedSamplesMaxDepth + +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. + +### hidePropertiesPrefix + +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_ + ## Deprecated Functional settings ### hideDownloadButton diff --git a/docs/redoc-vendor-extensions.md b/docs/redoc-vendor-extensions.md index 3a26fb8c..7721bb4b 100644 --- a/docs/redoc-vendor-extensions.md +++ b/docs/redoc-vendor-extensions.md @@ -42,12 +42,15 @@ You can use the following [vendor extensions](https://redocly.com/docs/openapi-v - [x-explicitMappingOnly](#x-explicitmappingonly) - [How to use with Redoc](#how-to-use-with-redoc-10) - [x-explicitMappingOnly example](#x-explicitmappingonly-example) + - [x-enumDescriptions](#x-enumdescriptions) + - [How to use with Redoc](#how-to-use-with-redoc-11) + - [x-enumDescriptions example](#x-enumdescriptions-example) ## Swagger Object Extends the OpenAPI root [OpenAPI Object](https://redocly.com/docs/openapi-visual-reference/openapi) ### x-servers -Backported from OpenAPI 3.0 [`servers`](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#serverObject). Currently doesn't support templates. +Backported from OpenAPI 3.0 [`servers`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#server-object). Currently doesn't support templates. ### x-tagGroups @@ -320,3 +323,31 @@ Pet: ``` Shows in the selectpicker only the items `cat` and `bee`, even though the `Dog` class inherits from the `Pet` class. + +### x-enumDescriptions +| Field Name | Type | Description | +| :------------- | :------: | :---------- | +| x-enumDescriptions | [[Enum Description Object](https://redocly.com/docs/realm/author/reference/openapi-extensions/x-enum-descriptions#enum-description-object)] | A list of the enum values and descriptions to include in the documentation. | + +#### How to use with Redoc +The enum (short for "enumeration") fields in OpenAPI allow you to restrict the value of a field to a list of allowed values. These values need to be short and machine-readable, but that can make them harder for humans to parse and work with. + +Add x-enumDescriptions to your OpenAPI description to show a helpful table of enum options and an explanation of what each one means. This field supports Markdown. + +#### x-explicitMappingOnly example +The following example shows a schema with two short-named options, and the x-enumDescriptions entry to list all enum entries and give additional context for each: + +```yaml +components: + schemas: + TicketType: + description: Type of ticket being purchased. Use `general` for regular museum entry and `event` for tickets to special events. + type: string + enum: + - event + - general + x-enumDescriptions: + event: Event Tickets _(timed entry)_ + general: General Admission + example: event +```