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

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

* docs: updates product name from ReDoc to Redoc

.github/CONTRIBUTING.md

@@ -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)
+- [Redoc Contributing Guide](#redoc-contributing-guide)
-- [Pull Request Guidelines](#pull-request-guidelines)
+  - [Issue Reporting Guidelines](#issue-reporting-guidelines)
-- [Development Setup](#development-setup)
+  - [Pull Request Guidelines](#pull-request-guidelines)
-- [Project Structure](#project-structure)
+  - [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

.github/pull_request_template.md

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

.github/styles/Rules/BritishEnglish.yml

@@ -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

.github/styles/Rules/FutureTense.yml

@@ -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]*)"

.github/styles/Rules/HeaderGerunds.yml

@@ -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.*'

.github/styles/Rules/InclusionGenderCulture.yml

@@ -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

.github/styles/Rules/OxfordComma.yml

@@ -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+[.?!]'

.github/styles/Vocab/Rules/accept.txt

@@ -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

.github/workflows/vale.yaml

@@ -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}}

.vale.ini

@@ -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]

CHANGELOG.md

@@ -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

README.md

@@ -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.

docs/deployment/html.md

@@ -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.
 

docs/deployment/intro.md

@@ -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)

docs/redoc-vendor-extensions.md

@@ -2,29 +2,52 @@
 
 You can use the following [vendor extensions](https://swagger.io/specification/#specificationExtensions) with Redoc.
 
-- [Swagger Object](#swagger-object)
+- [Redoc vendor extensions](#redoc-vendor-extensions)
+    - [Swagger Object](#swagger-object)
       - [x-servers](#x-servers)
       - [x-tagGroups](#x-taggroups)
-	- [Tag Group Object](#a-nametaggroupobjectatag-group-object)
+          - [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)
-- [Info Object](#info-object)
+          - [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)
-	- [Logo Object](#a-namelogoobjectalogo-object)
+          - [How to use with Redoc](#how-to-use-with-redoc-2)
-- [Tag Object](#tag-object)
+      - [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](#operation-object-vendor-extensions)
+    - [Operation Object vendor extensions](#operation-object-vendor-extensions)
       - [x-codeSamples](#x-codesamples)
-	- [Code Sample Object](#a-namecodesampleobjectacode-sample-object)
+          - [How to use with Redoc](#how-to-use-with-redoc-4)
-- [Parameter Object](#parameter-object)
+      - [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)
-- [Response Object vendor extensions](#response-object-vendor-extensions)
+          - [How to use with Redoc](#how-to-use-with-redoc-5)
+    - [Response Object vendor extensions](#response-object-vendor-extensions)
       - [x-summary](#x-summary)
-- [Schema Object](#schema-object)
+          - [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.

docs/security-definitions-injection.md

@@ -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.