Redocly/redoc
1
1
Fork 0
mirror of https://github.com/Redocly/redoc.git synced 2024-11-21 16:16:33 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs: adds vale rules and workflow for running in CI (#2348)

Browse Source 
* docs: adds vale rules and workflow for running in CI

* docs: updates product name from ReDoc to Redoc
This commit is contained in:
Heather Cloward 2023-07-11 13:31:52 -04:00 committed by GitHub
parent 4386867d90
commit c407726a66
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
17 changed files with 453 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
.github/CONTRIBUTING.md vendored
View File

@ -1,11 +1,13 @@
# ReDoc Contributing Guide
# Redoc Contributing Guide
Hi! We're really excited that you are interested in contributing to ReDoc. Before submitting your contribution though, please make sure to take a moment and read through the following guidelines.
Hi! We're really excited that you are interested in contributing to Redoc. Before submitting your contribution though, please make sure to take a moment and read through the following guidelines.
- [Issue Reporting Guidelines](#issue-reporting-guidelines)
- [Pull Request Guidelines](#pull-request-guidelines)
- [Development Setup](#development-setup)
- [Project Structure](#project-structure)
- [Redoc Contributing Guide](#redoc-contributing-guide)
- [Issue Reporting Guidelines](#issue-reporting-guidelines)
- [Pull Request Guidelines](#pull-request-guidelines)
- [Development Setup](#development-setup)
- [Commonly used NPM scripts](#commonly-used-npm-scripts)
- [Project Structure](#project-structure)
## Issue Reporting Guidelines
- Before filing a new issue, try to make sure your problem doesn’t already exist.
@ -22,7 +24,7 @@ Before submitting a pull request, please make sure the following is done:
## Development Setup
You will need [Node.js](http://nodejs.org) at `v12.0.0+`.
You need [Node.js](http://nodejs.org) at `v12.0.0+`.
After cloning the repo, run:
@ -88,7 +90,7 @@ There are some other scripts available in the `scripts` section of the `package.
- **`src/common-elements`**: contains common Styled elements or components used in multiple places
- **`src/components`**: contains main visual components
- **`src/services`**: contains different services used by ReDoc including MobX stores
- **`src/services`**: contains different services used by Redoc including MobX stores
- **`src/services/models`**: contains classes for OpenAPI entities (e.g. Response, Operations, etc)
- **`src/types`**: contains extra typescript typings including OpenAPI doc typings
- **`src/utils`**: utility functions

2
.github/pull_request_template.md vendored
View File

@ -2,7 +2,7 @@
## Reference
## Testing
## Tests
## Screenshots (optional)

110
.github/styles/Rules/BritishEnglish.yml vendored Normal file
View File

@ -0,0 +1,110 @@
extends: substitution
message: 'Use the US spelling "%s" instead of British "%s".'
link: https://docs.microsoft.com/en-us/style-guide/word-choice/use-us-spelling-avoid-non-english-words
level: error
ignorecase: true
swap:
aeon: eon
aeroplane: airplane
ageing: aging
aluminium: aluminum
anaemia: anemia
anaesthesia: anesthesia
analyse: analyze
annexe: annex
apologise: apologize
behaviour: behavior
busses: buses
calibre: caliber
cancelled: canceled
cancellation: cancelation
catalogue: catalog
categorise: categorize
categorised: categorized
categorises: categorizes
categorising: categorizing
centre: center
cheque: check
civilisation: civilization
civilise: civilize
colour: color
cosy: cozy
cypher: cipher
dependant: dependent
defence: defense
distil: distill
draught: draft
encyclopaedia: encyclopedia
enquiry: inquiry
enrol: enroll
enrolment: enrollment
enthral: enthrall
expiry: expiration
favourite: favorite
fibre: fiber
fillet: filet
flavour: flavor
furore: furor
fulfil: fulfill
gaol: jail
grey: gray
humour: humor
honour: honor
initialled: initialed
initialling: initialing
instil: instill
jewellery: jewelry
labelling: labeling
labelled: labeled
labour: labor
libellous: libelous
licence: license
likeable: likable
liveable: livable
lustre: luster
manoeuvre: maneuver
marvellous: marvelous
matt: matte
meagre: meager
metre: meter
modelling: modeling
moustache: mustache
neighbour: neighbor
normalise: normalize
offence: offense
organise: organize
organisation: organization
orientated: oriented
paralyse: paralyze
plough: plow
pretence: pretense
programme: program
pyjamas: pajamas
rateable: ratable
realise: realize
recognise: recognize
reconnoitre: reconnoiter
rumour: rumor
sabre: saber
saleable: salable
saltpetre: saltpeter
sceptic: skeptic
sepulchre: sepulcher
signalling: signaling
sizeable: sizable
skilful: skillful
sombre: somber
smoulder: smolder
speciality: specialty
spectre: specter
splendour: splendor
standardise: standardize
standardised: standardized
sulphur: sulfur
theatre: theater
travelled: traveled
traveller: traveler
travelling: traveling
unshakeable: unshakable
wilful: willful
yoghurt: yogurt

10
.github/styles/Rules/FutureTense.yml vendored Normal file
View File

@ -0,0 +1,10 @@
extends: existence
message: 'Avoid using future tense: "%s". Use present tense instead.'
link: https://intranet.redoc.ly/contributing/documentation-style-guide/#tone-and-audience
ignorecase: true
level: error
raw:
- "(going to( |\n|[[:punct:]])[a-zA-Z]*|"
- "will( |\n|[[:punct:]])[a-zA-Z]*|"
- "won't( |\n|[[:punct:]])[a-zA-Z]*|"
- "[a-zA-Z]*'ll( |\n|[[:punct:]])[a-zA-Z]*)"

7
.github/styles/Rules/HeaderGerunds.yml vendored Normal file
View File

@ -0,0 +1,7 @@
extends: existence
message: 'Do not start headings with with a gerund (ing word). Use an imperative verb instead.'
link: https://intranet.redoc.ly/contributing/documentation-style-guide/#content-organization
level: error
scope: heading
tokens:
- '^\w*ing.*'

16
.github/styles/Rules/InclusionGenderCulture.yml vendored Normal file
View File

@ -0,0 +1,16 @@
extends: substitution
message: 'Use inclusive language. Consider "%s" instead of "%s".'
link: https://intranet.redoc.ly/contributing/documentation-style-guide/#grammar-and-syntax
level: error
ignorecase: true
swap:
he: they
his: their
she: they
hers: their
blacklist(?:ed|ing|s)?: blocklist
whitelist(?:ed|ing|s)?: allowlist
master: primary, main
slave: replica
he/she: they
s/he: they

8
.github/styles/Rules/OxfordComma.yml vendored Normal file
View File

@ -0,0 +1,8 @@
extends: existence
message: "Use the Oxford comma in '%s'."
link: https://docs.microsoft.com/en-us/style-guide/punctuation/commas
scope: sentence
level: error
nonword: true
tokens:
- '(?:[^\s,]+,){1,} \w+ (?:and|or) \w+[.?!]'

150
.github/styles/Vocab/Rules/accept.txt vendored Normal file
View File

@ -0,0 +1,150 @@
[Aa]nsible
[Aa]utostart
[Bb]locklist
[Bb]locklists
[Bb]oolean
[Bb]reakpoint
[B]reakpoints
[Cc]ancelation
[Cc]lassloading
[Cc]hargeback
[Cc]hargebacks
[Cc]he
[Cc]rypto
[Cc]ryptocurrency
[Dd]evfile|[Dd]evfiles
[Dd]ownstream
[Dd]ownstreaming
[Ff]actories|[Ff]actory
[Gg]it
[Gg]rafana
[Hh]eatmap
[Hh]elm
[Hh]ostname
[Ii]tem
[Jj]etbrains
[Kk]eycloak
[Ll]iveness
[Ll]ombok
[Ll]oopback
[Mm]aven
[Mm]inikube
[Mm]inishift
[Mm]ixin|[Mm]ixins
[Mm]odularization
[Mm]ulticluster
[Mm]ultihost
[Mm]ultinode
[Mm]ultitenant
[Mm]ultiuser
[Mm]ultizone
[Nn]amespace|[Nn]amespaces
[Nn]etcoredebug[Oo]utput
[Nn]ginx
[Oo]nboarding
[Pp]podman
[Pp]reconfigured
[Rr]eadonly
[Rr]epresentment
[Rr]ollout|[Rr]ollouts
[Rr]untime|[Rr]untimes
[Ss]erializer
[Ss]erverless
[Ss]ubnetwork
[Ss]ubpath|[Ss]ubpaths
[Tt]heia
[Tt]olerations
[Tt]ruststore
[Uu]ninstallation
[Uu]nstaged
[Uu]ntrusted
[Ww]orkspace|[Ww]orkspaces
[Yy]eoman
\.NET
adoc
Antora
API
Apigee
AsciiDoc
AWS|aws
Azure
Bierner
Bitbucket
btn
Btrfs
CentOS
Ceph
Che-Theia
CLI
ConfigMap|ConfigMaps
Ctrl
DaemonSet
Dev Workspace
Developer Perspective
DNS
Docker
Dockerfile
Dotnet
Endevor
endif
GitHub|github
GitLab
Gluster
Gradle
Grafana
GUI
HTTPS|https
I/O
IDE|ide|IDEs
Intelephense
IntelliJ IDEA
Java
Java Lombok
JSON|json
JVM|jvm
kbd
Kubespray
Laravel
Let\'s Encrypt
Mattermost
mebibytes
Microsoft Azure
millicores
Mulesoft
MySQL
Netlify
Node.js
npm
NuGet
OAuth
ocp
OmniSharp
OpenShift
OpenTracing
Operator
OperatorHub
OpenAPI
osd
PHP
PostgreSQL
Quarkus
Rebilly
Redoc
Redocly
Redocly-cli
SCM
Sharding
SonarLint
Spring Boot
SVG
Uber
URI|URIs
URL|url|URLs
Velero
Vercel
Visual Studio Code
vsix
Webview|Webviews
Woopra
YAML|yaml
Zowe

0
.github/styles/Vocab/Rules/reject.txt vendored Normal file
View File

16
.github/workflows/vale.yaml vendored Normal file
View File

@ -0,0 +1,16 @@
name: Docs lint
on:
pull_request:
types: [opened, synchronize, reopened]
jobs:
vale:
name: vale action
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: errata-ai/vale-action@reviewdog
with:
files: '["README.md", "docs"]'
env:
GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

48
.vale.ini Normal file
View File

@ -0,0 +1,48 @@
# Vale configuration file.
# See: https://docs.errata.ai/vale/config
# The relative path to the folder containing linting rules (styles).
StylesPath = .github/styles
# Vocab define the exceptions to use in *all* `BasedOnStyles`.
# spelling-exceptions.txt triggers `Vale.Terms`
# reject.txt triggers `Vale.Avoid`
# See: https://docs.errata.ai/vale/vocab
Vocab = Rules
# Minimum alert level
# -------------------
# The minimum alert level in the output (suggestion, warning, or error).
# If integrated into CI, builds fail by default on error-level alerts, unless you run Vale with the --no-exit flag
MinAlertLevel = suggestion
# IgnoredScopes specifies inline-level HTML tags to ignore.
# These tags may occur in an active scope (unlike SkippedScopes, skipped entirely) but their content still won't raise any alerts.
# Default: ignore `code` and `tt`.
IgnoredScopes = code, tt, img, url, a, body.id
# SkippedScopes specifies block-level HTML tags to ignore. Ignore any content in these scopes.
# Default: ignore `script`, `style`, `pre`, and `figure`.
# For AsciiDoc: by default, listingblock, and literalblock.
SkippedScopes = script, style, pre, figure, code, tt, listingblock, literalblock
# Rules for matching file types. See: https://docs.errata.ai/vale/scoping
[formats]
properties = md
mdx = md
# Rules for .MD, .MDX
[*.{md,mdx}]
BasedOnStyles = Rules
# Ignore code surrounded by backticks or plus sign, parameters defaults, URLs.
TokenIgnores = (\x60[^\n\x60]+\x60), ([^\n]+=[^\n]*), (\+[^\n]+\+), (http[^\n]+\[)
Vale.Repetition = NO
Vale.SentenceSpacing = NO
Vale.Spelling = NO
# /End of rules for .MD, .MDX
# Process .ini files
[*.ini]

6
CHANGELOG.md
View File

@ -498,7 +498,7 @@ closes: [#1506](https://github.com/Redocly/redoc/issues/1506), [#1478](https://g
### Bug Fixes
* invalid discriminator dropdown behaviour with enum ([be07197](https://github.com/Redocly/redoc/commit/be07197e6d1e85a3fd3e61189a36b288751c077d))
* invalid discriminator dropdown behavior with enum ([be07197](https://github.com/Redocly/redoc/commit/be07197e6d1e85a3fd3e61189a36b288751c077d))
@ -716,7 +716,7 @@ Same as rc.31 by mistake
### Bug Fixes
* empty servers behaviour per OAS spec ([ed1db0c](https://github.com/Redocly/redoc/commit/ed1db0c9027087ae0ae923e390e3e1d638a647ae)), closes [#1151](https://github.com/Redocly/redoc/issues/1151)
* empty servers behavior per OAS spec ([ed1db0c](https://github.com/Redocly/redoc/commit/ed1db0c9027087ae0ae923e390e3e1d638a647ae)), closes [#1151](https://github.com/Redocly/redoc/issues/1151)
* fix duplicated content in tags when using md headings ([a260c84](https://github.com/Redocly/redoc/commit/a260c8414c34a259a70a20ebcd20ecbb06c3d250)), closes [#1150](https://github.com/Redocly/redoc/issues/1150) [#1152](https://github.com/Redocly/redoc/issues/1152)
* use mobile menu background color value from theme ([#1144](https://github.com/Redocly/redoc/issues/1144)) ([41a9b3c](https://github.com/Redocly/redoc/commit/41a9b3c18228d236d182d3c15c9abc35ae72a0d5))
@ -1694,7 +1694,7 @@ Complete rewrite also means that this rewrite may introduce issues, but they sho
- no more GitHub pages-based CDN. Use [unpkg.com](https://unpkg.com/) to access ReDoc releases
### Known Regression (will be resolved before leaving alpha stage)
### Known Regression (resolved before leaving alpha stage)
- `lazyLoading` option not implemented yet
- Copying to clipboard of samples not implemented yet
- Search not implemented yet

14
README.md
View File

@ -25,7 +25,7 @@ By default Redoc offers a three-panel, responsive layout:
## Live demo
If you want to see how Redoc will render your OpenAPI definition,
If you want to see how Redoc renders your OpenAPI definition,
you can try it out online at https://redocly.github.io/redoc/.
A version of the Swagger Petstore API is displayed by default.
@ -109,7 +109,7 @@ Refer to the Redocly's documentation for more information on these products:
Additionally, all the 1.x releases are hosted on our GitHub Pages-based CDN **(deprecated)**:
- particular release, for example `v1.2.0`: https://rebilly.github.io/ReDoc/releases/v1.2.0/redoc.min.js
- `v1.x.x` release: https://rebilly.github.io/ReDoc/releases/v1.x.x/redoc.min.js
- `latest` release: https://rebilly.github.io/ReDoc/releases/latest/redoc.min.js - it will point to latest 1.x.x release since 2.x releases are not hosted on this CDN but on unpkg.
- `latest` release: https://rebilly.github.io/ReDoc/releases/latest/redoc.min.js - points to latest 1.x.x release since 2.x releases are not hosted on this CDN but on unpkg.
## Version Guidance
| Redoc Release | OpenAPI Specification |
@ -214,7 +214,7 @@ You can use all of the following options with the standalone version of the <red
* `maxDisplayedEnumValues` - display only specified number of enum values. hide rest values under spoiler.
* `hideDownloadButton` - do not show "Download" spec button. **THIS DOESN'T MAKE YOUR SPEC PRIVATE**, it just hides the button.
* `downloadFileName` - set a custom file name for the downloaded API definition file.
* `downloadDefinitionUrl` - If the 'Download' button is visible in the API reference documentation (hideDownloadButton=false), the URL configured here will open when that button is selected. Provide it as an absolute URL with the full URI scheme.
* `downloadDefinitionUrl` - If the 'Download' button is visible in the API reference documentation (hideDownloadButton=false), the URL configured here opens when that button is selected. Provide it as an absolute URL with the full URI scheme.
* `hideHostname` - if set, the protocol and hostname is not shown in the operation definition.
* `hideLoading` - do not show loading animation. Useful for small docs.
* `hideFab` - do not show FAB in mobile view. Useful for implementing a custom floating action button.
@ -230,7 +230,7 @@ You can use all of the following options with the standalone version of the <red
* `sortOperationsAlphabetically` - set to true, sorts operations in the navigation sidebar and in the middle panel alphabetically
* `sortTagsAlphabetically` - set to true, sorts tags in the navigation sidebar and in the middle panel alphabetically
* `lazyRendering` - _Not implemented yet_ ~~if set, enables lazy rendering mode in ReDoc. This mode is useful for APIs with big number of operations (e.g. > 50). In this mode ReDoc shows initial screen ASAP and then renders the rest operations asynchronously while showing progress bar on the top. Check out the [demo](\\redocly.github.io/redoc) for the example.~~
* `menuToggle` - if true clicking second time on expanded menu item will collapse it, default `true`.
* `menuToggle` - if true, clicking second time on expanded menu item collapses it, default `true`.
* `nativeScrollbars` - use native scrollbar for sidemenu instead of perfect-scroll (scrolling performance optimization for big specs).
* `onlyRequiredInSamples` - shows only required fields in request samples.
* `pathInMiddlePanel` - show path link and HTTP verb in the middle panel instead of the right one.
@ -238,14 +238,14 @@ You can use all of the following options with the standalone version of the <red
* `scrollYOffset` - If set, specifies a vertical scroll-offset. This is often useful when there are fixed positioned elements at the top of the page, such as navbars, headers etc;
`scrollYOffset` can be specified in various ways:
* **number**: A fixed number of pixels to be used as offset.
* **selector**: selector of the element to be used for specifying the offset. The distance from the top of the page to the element's bottom will be used as offset.
* **selector**: 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 offset.
* **function**: A getter function. Must return a number representing the offset (in pixels).
* `showExtensions` - show vendor extensions ("x-" fields). Extensions used by Redoc are ignored. Can be boolean or an array of `string` with names of extensions to display.
* `sortPropsAlphabetically` - sort properties alphabetically.
* `payloadSampleIdx` - if set, payload sample will be inserted at this index or last. Indexes start from 0.
* `payloadSampleIdx` - if set, payload sample is inserted at this index or last. Indexes start from 0.
* `theme` - Redoc theme. For details check [theme docs](#redoc-theme-object).
* `untrustedSpec` - if set, the spec is considered untrusted and all HTML/markdown is sanitized to prevent XSS. **Disabled by default** for performance reasons. **Enable this option if you work with untrusted user data!**
* `nonce` - if set, the provided value will be injected in every injected HTML element in the `nonce` attribute. Useful when using CSP, see https://webpack.js.org/guides/csp/.
* `nonce` - if set, the provided value is injected in every injected HTML element in the `nonce` attribute. Useful when using CSP, see https://webpack.js.org/guides/csp/.
* `sideNavStyle` - can be specified in various ways:
* **summary-only**: displays a summary in the sidebar navigation item. (**default**)
* **path-only**: displays a path in the sidebar navigation item.

4
docs/deployment/html.md
View File

@ -16,7 +16,7 @@ You can install Redoc using one of the following package managers:
:::attention Initialize your package manager
If you do not have a `package.json` file in your project directory,
you need to add one by initializing npm or yarn in your project. Use the command `npm init` for npm,
or `yarn init` for yarn. These initialization commands will lead you through the process
or `yarn init` for yarn. These initialization commands lead you through the process
of creating a `package.json` file in your project.
For more information, see
@ -98,7 +98,7 @@ Redoc.init(specOrSpecUrl, options, element, callback)
- `specOrSpecUrl`: Either a JSON object with the OpenAPI definition or a URL to the
definition in JSON or YAML format.
- `options`: See [`theme.openapi` object](/docs/api-reference-docs/configuration/functionality.mdx) reference.
- `element`: DOM element Redoc will be inserted into.
- `element`: DOM element Redoc is inserted into.
- `callback`(optional): Callback to be called after Redoc has been fully rendered.
It is also called on errors with `error` as the first argument.

4
docs/deployment/intro.md
View File

@ -12,7 +12,7 @@ You should select the option that best fits your needs.
The following options are supported:
- **[Live demo](https://redocly.github.io/redoc/):**
The live demo offers a fast way to see how your OpenAPI will render with Redoc.
The live demo offers a fast way to see how your OpenAPI renders with Redoc.
A version of the Swagger Petstore API is displayed by default. To test it with your own OpenAPI definition, enter the URL for your
definition and select **TRY IT**.
- **[HTML element](./html.md):**
@ -28,7 +28,7 @@ The following options are supported:
### OpenAPI definition
You will need an OpenAPI definition. For testing purposes, you can use one of the following sample OpenAPI definitions:
You need an OpenAPI definition. For testing purposes, you can use one of the following sample OpenAPI definitions:
- OpenAPI 3.0
- [Rebilly Users OpenAPI Definition](https://raw.githubusercontent.com/Rebilly/api-definitions/main/openapi/users.yaml)

81
docs/redoc-vendor-extensions.md
View File

@ -2,29 +2,52 @@
You can use the following [vendor extensions](https://swagger.io/specification/#specificationExtensions) with Redoc.
- [Swagger Object](#swagger-object)
- [x-servers](#x-servers)
- [x-tagGroups](#x-taggroups)
- [Tag Group Object](#a-nametaggroupobjectatag-group-object)
- [x-ignoredHeaderParameters](#x-ignoredheaderparameters)
- [Info Object](#info-object)
- [x-logo](#x-logo)
- [Logo Object](#a-namelogoobjectalogo-object)
- [Tag Object](#tag-object)
- [x-traitTag](#x-traittag)
- [x-displayName](#x-displayname)
- [Operation Object](#operation-object-vendor-extensions)
- [x-codeSamples](#x-codesamples)
- [Code Sample Object](#a-namecodesampleobjectacode-sample-object)
- [Parameter Object](#parameter-object)
- [x-examples](#x-examples)
- [Response Object vendor extensions](#response-object-vendor-extensions)
- [x-summary](#x-summary)
- [Schema Object](#schema-object)
- [x-nullable](#x-nullable)
- [x-extendedDiscriminator](#x-extendeddiscriminator)
- [x-additionalPropertiesName](#x-additionalpropertiesname)
- [x-explicitMappingOnly](#x-explicitmappingonly)
- [Redoc vendor extensions](#redoc-vendor-extensions)
- [Swagger Object](#swagger-object)
- [x-servers](#x-servers)
- [x-tagGroups](#x-taggroups)
- [How to use with Redoc](#how-to-use-with-redoc)
- [Tag Group Object](#tag-group-object)
- [Fixed fields](#fixed-fields)
- [x-tagGroups example](#x-taggroups-example)
- [x-ignoredHeaderParameters](#x-ignoredheaderparameters)
- [How to use with Redoc](#how-to-use-with-redoc-1)
- [x-ignoredHeaderParameters example](#x-ignoredheaderparameters-example)
- [Info Object](#info-object)
- [x-logo](#x-logo)
- [How to use with Redoc](#how-to-use-with-redoc-2)
- [Logo Object](#logo-object)
- [Fixed fields](#fixed-fields-1)
- [x-logo example](#x-logo-example)
- [Tag Object](#tag-object)
- [x-traitTag](#x-traittag)
- [How to use with Redoc](#how-to-use-with-redoc-3)
- [x-traitTag example](#x-traittag-example)
- [x-displayName](#x-displayname)
- [Operation Object vendor extensions](#operation-object-vendor-extensions)
- [x-codeSamples](#x-codesamples)
- [How to use with Redoc](#how-to-use-with-redoc-4)
- [Code Sample Object](#code-sample-object)
- [Fixed fields](#fixed-fields-2)
- [Code Sample Object example](#code-sample-object-example)
- [Parameter Object](#parameter-object)
- [x-examples](#x-examples)
- [How to use with Redoc](#how-to-use-with-redoc-5)
- [Response Object vendor extensions](#response-object-vendor-extensions)
- [x-summary](#x-summary)
- [How to use with Redoc](#how-to-use-with-redoc-6)
- [Schema Object](#schema-object)
- [x-nullable](#x-nullable)
- [How to use with Redoc](#how-to-use-with-redoc-7)
- [x-extendedDiscriminator](#x-extendeddiscriminator)
- [How to use with Redoc](#how-to-use-with-redoc-8)
- [x-extendedDiscriminator example](#x-extendeddiscriminator-example)
- [x-additionalPropertiesName](#x-additionalpropertiesname)
- [How to use with Redoc](#how-to-use-with-redoc-9)
- [x-additionalPropertiesName example](#x-additionalpropertiesname-example)
- [x-explicitMappingOnly](#x-explicitmappingonly)
- [How to use with Redoc](#how-to-use-with-redoc-10)
- [x-explicitMappingOnly example](#x-explicitmappingonly-example)
### Swagger Object
Extends the OpenAPI root [OpenAPI Object](https://swagger.io/specification/#oasObject)
@ -40,7 +63,7 @@ Backported from OpenAPI 3.0 [`servers`](https://github.com/OAI/OpenAPI-Specifica
###### How to use with Redoc
`x-tagGroups` is used to group tags in the side menu.
Before you use `x-tagGroups`, make sure you **add all tags to a group**, since a tag that is not in a group, **will not be displayed** at all!
Before you use `x-tagGroups`, make sure you **add all tags to a group**, since a tag that is not in a group, **is not displayed** at all!
#### <a name="tagGroupObject"></a>Tag Group Object
Information about tags group
@ -89,7 +112,7 @@ x-tagGroups:
###### How to use with Redoc
Use `x-ignoredHeaderParameters` to specify header parameter names which are ignored by ReDoc.
Use `x-ignoredHeaderParameters` to specify header parameter names which are ignored by Redoc.
###### x-ignoredHeaderParameters example
```yaml
@ -204,7 +227,7 @@ Operation code sample
| Field Name | Type | Description |
| :---------- | :------: | :----------- |
| lang | string | Code sample language. Value should be one of the following [list](https://github.com/github/linguist/blob/master/lib/linguist/popular.yml) |
| label | string? | Code sample label e.g. `Node` or `Python2.7`, _optional_, `lang` will be used by default |
| label | string? | Code sample label, for example `Node` or `Python2.7`, _optional_, `lang` is used by default |
| source | string | Code sample source code |
@ -264,7 +287,7 @@ Schemas marked as `x-nullable` are marked in Redoc with the label Nullable
###### How to use with Redoc
Redoc uses this vendor extension to solve name-clash issues with the standard `discriminator`.
Value of this field specifies the field which will be used as a extended discriminator.
Value of this field specifies the field which is used as an extended discriminator.
Redoc displays definition with selectpicker using which user can select value of the `x-extendedDiscriminator`-marked field.
Redoc displays the definition derived from the current (using `allOf`) and has `enum` with only one value which is the same as the selected value of the field specified as `x-extendedDiscriminator`.
@ -347,7 +370,7 @@ Extends the `discriminator` property of the schema object.
###### How to use with Redoc
Redoc uses this extension to filter the `discriminator` mappings shown in the selectpicker.
When set to `true`, the selectpicker will only list the the explicitly defined mappings. When `false`, the default behavior is kept, i.e. explicit and implicit mappings will be shown.
When set to `true`, the selectpicker lists only the explicitly defined mappings. When `false`, the default behavior is kept, in other words, explicit and implicit mappings are shown.
###### x-explicitMappingOnly example
@ -366,4 +389,4 @@ Pet:
bee: "#/components/schemas/HoneyBee"
```
Will show in the selectpicker only the items `cat` and `bee`, even though the `Dog` class inherits from the `Pet` class.
Shows in the selectpicker only the items `cat` and `bee`, even though the `Dog` class inherits from the `Pet` class.

16
docs/security-definitions-injection.md
View File

@ -1,19 +1,23 @@
# Injection security definitions
You can inject Security Definitions widget into any place of your specification `description`:
You can inject the Security Definitions widget anywhere in your specification `description`:
```markdown
...
# Authorization
Some description
<!-- ReDoc-Inject: <security-definitions> -->
<!-- Redoc-Inject: <security-definitions> -->
...
```
Inject instruction is wrapped into HTML comment so it is **visible only in ReDoc**. It won't be visible e.g. in SwaggerUI.
The inject instruction is wrapped in an HTML comment,
so it is **visible only in Redoc** and not visible, for instance, in the SwaggerUI.
# Default behavior
If injection tag is not found in the description it will be appended to the end
of description under `Authentication` header.
If `Authentication` header is already present in the description, Security Definitions won't be inserted and rendered at all.
If the injection tag is not found in the description, it is appended to the end
of description under the `Authentication` header.
If the `Authentication` header is already present in the description,
Security Definitions are not inserted or rendered.