mirror of
https://github.com/Redocly/redoc.git
synced 2024-09-20 18:58:57 +03:00
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
This commit is contained in:
Heather Cloward
GitHub
parent
4386867d90
commit
c407726a66
18
.github/CONTRIBUTING.md
vendored
18
.github/CONTRIBUTING.md
vendored
|
|
@ -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
2
.github/pull_request_template.md
vendored
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
## Reference
|
||||
|
||||
## Testing
|
||||
## Tests
|
||||
|
||||
## Screenshots (optional)
|
||||
|
||||
|
|
|
|||
110
.github/styles/Rules/BritishEnglish.yml
vendored
Normal file
110
.github/styles/Rules/BritishEnglish.yml
vendored
Normal 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
10
.github/styles/Rules/FutureTense.yml
vendored
Normal 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
7
.github/styles/Rules/HeaderGerunds.yml
vendored
Normal 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
16
.github/styles/Rules/InclusionGenderCulture.yml
vendored
Normal 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
8
.github/styles/Rules/OxfordComma.yml
vendored
Normal 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
150
.github/styles/Vocab/Rules/accept.txt
vendored
Normal 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
0
.github/styles/Vocab/Rules/reject.txt
vendored
Normal file
16
.github/workflows/vale.yaml
vendored
Normal file
16
.github/workflows/vale.yaml
vendored
Normal 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
48
.vale.ini
Normal 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]
|
||||
|
|
@ -159,7 +159,7 @@
|
|||
|
||||
* implement configurable minimum characer length to init search ([#1402](https://github.com/Redocly/redoc/issues/1402)) ([0fa08fa](https://github.com/Redocly/redoc/commit/0fa08faab1c176a4bfc5a553e8e8f8b07aca659f))
|
||||
* support OAS 3.1 unevaluatedProperties ([#1978](https://github.com/Redocly/redoc/issues/1978)) ([0755ac6](https://github.com/Redocly/redoc/commit/0755ac6f04514eb0c08f90afceeda7858206b435))
|
||||
* publish dockerhub ([#1971](https://github.com/Redocly/redoc/issues/1971)) ([7e01a0](https://github.com/Redocly/redoc/commit/7e01a0cfe2ad8d06075bfc66ef3860edbef033f8))
|
||||
* publish dockerhub ([#1971](https://github.com/Redocly/redoc/issues/1971)) ([7e01a0](https://github.com/Redocly/redoc/commit/7e01a0cfe2ad8d06075bfc66ef3860edbef033f8))
|
||||
|
||||
|
||||
# [2.0.0-rc.67](https://github.com/Redocly/redoc/compare/v2.0.0-rc.66...v2.0.0-rc.67) (2022-04-28)
|
||||
|
|
@ -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
14
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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user