mirror of
https://github.com/Redocly/redoc.git
synced 2024-11-10 19:06:34 +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:
parent
4386867d90
commit
c407726a66
10
.github/CONTRIBUTING.md
vendored
10
.github/CONTRIBUTING.md
vendored
|
@ -1,10 +1,12 @@
|
||||||
# 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.
|
||||||
|
|
||||||
|
- [Redoc Contributing Guide](#redoc-contributing-guide)
|
||||||
- [Issue Reporting Guidelines](#issue-reporting-guidelines)
|
- [Issue Reporting Guidelines](#issue-reporting-guidelines)
|
||||||
- [Pull Request Guidelines](#pull-request-guidelines)
|
- [Pull Request Guidelines](#pull-request-guidelines)
|
||||||
- [Development Setup](#development-setup)
|
- [Development Setup](#development-setup)
|
||||||
|
- [Commonly used NPM scripts](#commonly-used-npm-scripts)
|
||||||
- [Project Structure](#project-structure)
|
- [Project Structure](#project-structure)
|
||||||
|
|
||||||
## Issue Reporting Guidelines
|
## Issue Reporting Guidelines
|
||||||
|
@ -22,7 +24,7 @@ Before submitting a pull request, please make sure the following is done:
|
||||||
|
|
||||||
## Development Setup
|
## 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:
|
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/common-elements`**: contains common Styled elements or components used in multiple places
|
||||||
- **`src/components`**: contains main visual components
|
- **`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/services/models`**: contains classes for OpenAPI entities (e.g. Response, Operations, etc)
|
||||||
- **`src/types`**: contains extra typescript typings including OpenAPI doc typings
|
- **`src/types`**: contains extra typescript typings including OpenAPI doc typings
|
||||||
- **`src/utils`**: utility functions
|
- **`src/utils`**: utility functions
|
||||||
|
|
2
.github/pull_request_template.md
vendored
2
.github/pull_request_template.md
vendored
|
@ -2,7 +2,7 @@
|
||||||
|
|
||||||
## Reference
|
## Reference
|
||||||
|
|
||||||
## Testing
|
## Tests
|
||||||
|
|
||||||
## Screenshots (optional)
|
## 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]
|
|
@ -498,7 +498,7 @@ closes: [#1506](https://github.com/Redocly/redoc/issues/1506), [#1478](https://g
|
||||||
|
|
||||||
### Bug Fixes
|
### 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
|
### 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)
|
* 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))
|
* 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
|
- 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
|
- `lazyLoading` option not implemented yet
|
||||||
- Copying to clipboard of samples not implemented yet
|
- Copying to clipboard of samples not implemented yet
|
||||||
- Search 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
|
## 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/.
|
you can try it out online at https://redocly.github.io/redoc/.
|
||||||
|
|
||||||
A version of the Swagger Petstore API is displayed by default.
|
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)**:
|
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
|
- 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
|
- `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
|
## Version Guidance
|
||||||
| Redoc Release | OpenAPI Specification |
|
| 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.
|
* `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.
|
* `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.
|
* `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.
|
* `hideHostname` - if set, the protocol and hostname is not shown in the operation definition.
|
||||||
* `hideLoading` - do not show loading animation. Useful for small docs.
|
* `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.
|
* `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
|
* `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
|
* `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.~~
|
* `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).
|
* `nativeScrollbars` - use native scrollbar for sidemenu instead of perfect-scroll (scrolling performance optimization for big specs).
|
||||||
* `onlyRequiredInSamples` - shows only required fields in request samples.
|
* `onlyRequiredInSamples` - shows only required fields in request samples.
|
||||||
* `pathInMiddlePanel` - show path link and HTTP verb in the middle panel instead of the right one.
|
* `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` - 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:
|
`scrollYOffset` can be specified in various ways:
|
||||||
* **number**: A fixed number of pixels to be used as offset.
|
* **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).
|
* **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.
|
* `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.
|
* `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).
|
* `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!**
|
* `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:
|
* `sideNavStyle` - can be specified in various ways:
|
||||||
* **summary-only**: displays a summary in the sidebar navigation item. (**default**)
|
* **summary-only**: displays a summary in the sidebar navigation item. (**default**)
|
||||||
* **path-only**: displays a path in the sidebar navigation item.
|
* **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
|
:::attention Initialize your package manager
|
||||||
If you do not have a `package.json` file in your project directory,
|
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,
|
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.
|
of creating a `package.json` file in your project.
|
||||||
|
|
||||||
For more information, see
|
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
|
- `specOrSpecUrl`: Either a JSON object with the OpenAPI definition or a URL to the
|
||||||
definition in JSON or YAML format.
|
definition in JSON or YAML format.
|
||||||
- `options`: See [`theme.openapi` object](/docs/api-reference-docs/configuration/functionality.mdx) reference.
|
- `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.
|
- `callback`(optional): Callback to be called after Redoc has been fully rendered.
|
||||||
It is also called on errors with `error` as the first argument.
|
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:
|
The following options are supported:
|
||||||
|
|
||||||
- **[Live demo](https://redocly.github.io/redoc/):**
|
- **[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
|
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**.
|
definition and select **TRY IT**.
|
||||||
- **[HTML element](./html.md):**
|
- **[HTML element](./html.md):**
|
||||||
|
@ -28,7 +28,7 @@ The following options are supported:
|
||||||
|
|
||||||
### OpenAPI definition
|
### 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
|
- OpenAPI 3.0
|
||||||
- [Rebilly Users OpenAPI Definition](https://raw.githubusercontent.com/Rebilly/api-definitions/main/openapi/users.yaml)
|
- [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.
|
You can use the following [vendor extensions](https://swagger.io/specification/#specificationExtensions) with Redoc.
|
||||||
|
|
||||||
|
- [Redoc vendor extensions](#redoc-vendor-extensions)
|
||||||
- [Swagger Object](#swagger-object)
|
- [Swagger Object](#swagger-object)
|
||||||
- [x-servers](#x-servers)
|
- [x-servers](#x-servers)
|
||||||
- [x-tagGroups](#x-taggroups)
|
- [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)
|
- [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)
|
- [Info Object](#info-object)
|
||||||
- [x-logo](#x-logo)
|
- [x-logo](#x-logo)
|
||||||
- [Logo Object](#a-namelogoobjectalogo-object)
|
- [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)
|
- [Tag Object](#tag-object)
|
||||||
- [x-traitTag](#x-traittag)
|
- [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)
|
- [x-displayName](#x-displayname)
|
||||||
- [Operation Object](#operation-object-vendor-extensions)
|
- [Operation Object vendor extensions](#operation-object-vendor-extensions)
|
||||||
- [x-codeSamples](#x-codesamples)
|
- [x-codeSamples](#x-codesamples)
|
||||||
- [Code Sample Object](#a-namecodesampleobjectacode-sample-object)
|
- [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)
|
- [Parameter Object](#parameter-object)
|
||||||
- [x-examples](#x-examples)
|
- [x-examples](#x-examples)
|
||||||
|
- [How to use with Redoc](#how-to-use-with-redoc-5)
|
||||||
- [Response Object vendor extensions](#response-object-vendor-extensions)
|
- [Response Object vendor extensions](#response-object-vendor-extensions)
|
||||||
- [x-summary](#x-summary)
|
- [x-summary](#x-summary)
|
||||||
|
- [How to use with Redoc](#how-to-use-with-redoc-6)
|
||||||
- [Schema Object](#schema-object)
|
- [Schema Object](#schema-object)
|
||||||
- [x-nullable](#x-nullable)
|
- [x-nullable](#x-nullable)
|
||||||
|
- [How to use with Redoc](#how-to-use-with-redoc-7)
|
||||||
- [x-extendedDiscriminator](#x-extendeddiscriminator)
|
- [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)
|
- [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)
|
- [x-explicitMappingOnly](#x-explicitmappingonly)
|
||||||
|
- [How to use with Redoc](#how-to-use-with-redoc-10)
|
||||||
|
- [x-explicitMappingOnly example](#x-explicitmappingonly-example)
|
||||||
|
|
||||||
### Swagger Object
|
### Swagger Object
|
||||||
Extends the OpenAPI root [OpenAPI Object](https://swagger.io/specification/#oasObject)
|
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
|
###### How to use with Redoc
|
||||||
`x-tagGroups` is used to group tags in the side menu.
|
`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
|
#### <a name="tagGroupObject"></a>Tag Group Object
|
||||||
Information about tags group
|
Information about tags group
|
||||||
|
@ -89,7 +112,7 @@ x-tagGroups:
|
||||||
|
|
||||||
|
|
||||||
###### How to use with Redoc
|
###### 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
|
###### x-ignoredHeaderParameters example
|
||||||
```yaml
|
```yaml
|
||||||
|
@ -204,7 +227,7 @@ Operation code sample
|
||||||
| Field Name | Type | Description |
|
| 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) |
|
| 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 |
|
| 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
|
###### How to use with Redoc
|
||||||
Redoc uses this vendor extension to solve name-clash issues with the standard `discriminator`.
|
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 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`.
|
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
|
###### How to use with Redoc
|
||||||
Redoc uses this extension to filter the `discriminator` mappings shown in the selectpicker.
|
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
|
###### x-explicitMappingOnly example
|
||||||
|
|
||||||
|
@ -366,4 +389,4 @@ Pet:
|
||||||
bee: "#/components/schemas/HoneyBee"
|
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
|
# 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
|
```markdown
|
||||||
...
|
...
|
||||||
# Authorization
|
# Authorization
|
||||||
|
|
||||||
Some description
|
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
|
# 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