diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 99ecfcf7..997de311 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -11,7 +11,7 @@ Hi! We're really excited that you are interested in contributing to Redocly CLI. ## Issue Reporting Guidelines -- Before opening a new issue, try to make sure the same problem or idea hasn't already been reported. You can do that by going to the [Issues page](https://github.com/Redocly/redocly-cli/issues) in the repository and using the filter `is:issue` combined with some keywords relevant to your idea or problem. It helps us notice that more people have the same issue or use-case, and reduces the chance of getting your issue marked as a duplicate. Plus, you can even find some workarounds for your issue in the comments of a previously reported one! +- Before opening a new issue, try to make sure the same problem or idea hasn't already been reported. You can do that on the [Issues page](https://github.com/Redocly/redocly-cli/issues) in the repository and using the filter `is:issue` combined with some keywords relevant to your idea or problem. It helps us notice that more people have the same issue or use-case, and reduces the chance of getting your issue marked as a duplicate. Plus, you can even find some workarounds for your issue in the comments of a previously reported one! - The best way to get your bug fixed is to provide a (reduced) test case. This means listing and explaining the steps we should take to try and hit the same problem you're having. It helps us understand in which conditions the issue appears, and gives us a better idea of what may be causing it. @@ -29,7 +29,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+`. +[Node.js](http://nodejs.org) at `v12.0.0+` is required. After forking the repo, run: @@ -74,6 +74,18 @@ There are some other scripts available in the `scripts` section of the `package. ## Contribute documentation +### Prose linting + +We are proud of our docs. When you open a pull request, we lint the prose using [Vale](https://vale.sh/). You can also install this tool locally and run it from the root of the project with: + +``` +vale docs/ +``` + +The configuration is in `.vale.ini` in the root of the project. + +### Markdown link checking + We use [`mlc`](https://github.com/becheran/mlc) to check the links in the `docs/` folder. This tool runs automatically on every pull request, but you can also run it locally if you want to. Visit the project homepage to find the installation instructions for your platform, and then run the command like this: ``` diff --git a/.github/styles/Rules/BritishEnglish.yml b/.github/styles/Rules/BritishEnglish.yml new file mode 100644 index 00000000..6c33445f --- /dev/null +++ b/.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 diff --git a/.github/styles/Rules/FutureTense.yml b/.github/styles/Rules/FutureTense.yml new file mode 100644 index 00000000..1836c0e8 --- /dev/null +++ b/.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]*)" diff --git a/.github/styles/Rules/HeaderGerunds.yml b/.github/styles/Rules/HeaderGerunds.yml new file mode 100644 index 00000000..5f593070 --- /dev/null +++ b/.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.*' diff --git a/.github/styles/Rules/InclusionGenderCulture.yml b/.github/styles/Rules/InclusionGenderCulture.yml new file mode 100644 index 00000000..ea1b653e --- /dev/null +++ b/.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 diff --git a/.github/styles/Rules/OxfordComma.yml b/.github/styles/Rules/OxfordComma.yml new file mode 100644 index 00000000..163a5954 --- /dev/null +++ b/.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+[.?!]' diff --git a/.github/styles/Vocab/Rules/accept.txt b/.github/styles/Vocab/Rules/accept.txt new file mode 100644 index 00000000..039d46ed --- /dev/null +++ b/.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 diff --git a/.github/styles/Vocab/Rules/reject.txt b/.github/styles/Vocab/Rules/reject.txt new file mode 100644 index 00000000..e69de29b diff --git a/.github/workflows/vale.yaml b/.github/workflows/vale.yaml new file mode 100644 index 00000000..c5220c41 --- /dev/null +++ b/.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}} diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 00000000..5f29d079 --- /dev/null +++ b/.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] diff --git a/README.md b/README.md index c6698e21..3ea1a277 100644 --- a/README.md +++ b/README.md @@ -55,7 +55,7 @@ Redocly CLI is a great way to render API reference documentation. It uses open s redocly build-docs openapi.yaml ``` -Your API reference docs will be in `redoc-static.html` by default. You can customise this in many ways, [read the main docs](https://redocly.com/docs/cli/commands/build-docs) for more information. +Your API reference docs are in `redoc-static.html` by default. You can customize this in many ways. [Read the main docs](https://redocly.com/docs/cli/commands/build-docs) for more information. > :bulb: Redocly also has [hosted API reference docs](https://redocly.com/docs/api-registry/guides/api-registry-quickstart/), a (commercial) alternative to Redoc. Both Redoc and Redocly API reference docs can be worked on locally using the `preview-docs` command. @@ -71,7 +71,7 @@ redocly lint openapi.yaml **Format the output** in whatever way you need, the `stylish` output is as good as it sounds, but if you need JSON or Checkstyle outputs to integrate with other tools, we've got those too. -**Multiple files supported** so you don't need to bundle your API description in order to lint it, just give the entrypoint and Redocly CLI will do the rest. +**Multiple files supported** so you don't need to bundle your API description to lint it, just give the entry point and Redocly CLI does the rest. [Learn more about API standards and configuring Redocly rules](https://redocly.com/docs/cli/api-standards). diff --git a/docs/changelog.md b/docs/changelog.md index 39945d52..b15bf112 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -367,10 +367,10 @@ Technical release for changing the package name from `@redocly/openapi-cli` to ` The product name has changed from OpenAPI CLI to **Redocly CLI**. -You will notice this change reflected in all Redocly product documentation, in the npm package name (more on that in the "Deprecated" section), -and later in the official project GitHub repository. +This change is reflected in all Redocly product documentation, in the npm package name (more on that in the "Deprecated" section), +and in the official project GitHub repository. -The change also affects the CLI commands. The legacy name `openapi` will remain supported for a while, but we strongly recommend you use the new name `redocly`. +The change also affects the CLI commands. The legacy name `openapi` is supported for now, but we strongly recommend you use the new name `redocly`. (To illustrate, if you previously used `openapi lint`, now you should use `redocly lint`). If you encounter any issues and suspect they may be related to this change, let us know by [reporting an issue](https://github.com/Redocly/redocly-cli/issues). @@ -704,7 +704,7 @@ rules: ### Features -- Added three built-in decorators - `info-description-override`, `tag-description-override`, `operation-description-override` - that let you modify your API definitions during the bundling process. Use these decorators in the `lint` section of your `.redocly.yaml` file to point OpenAPI CLI to Markdown files with custom content. That custom content will replace any existing content in the `info.description` field, and in `tags.description` and `operation.description` fields for specified tag names and operation IDs. +- Added three built-in decorators - `info-description-override`, `tag-description-override`, `operation-description-override` - that let you modify your API definitions during the bundling process. Use these decorators in the `lint` section of your `.redocly.yaml` file to point OpenAPI CLI to Markdown files with custom content. That custom content replaces any existing content in the `info.description` field, and in `tags.description` and `operation.description` fields for specified tag names and operation IDs. The following examples show how to add the decorators to the `.redocly.yaml` file: @@ -839,7 +839,7 @@ lint: - Resolved an issue with transitive $ref resolution in the JSON schema validator. -- If the JSON schema validator crashes, OpenAPI CLI will now report the problem in the output instead of crashing itself. +- If the JSON schema validator crashes, OpenAPI CLI reports the problem in the output instead of crashing itself. --- @@ -903,7 +903,7 @@ lint: - Improved the error messages for `kebab-case` and implemented detection of `snake_case` usage in paths. -- The `join` command will no longer overwrite an existing `x-displayName` of a tag with the tag's `name` property. +- The `join` command does not overwrite an existing `x-displayName` of a tag with the tag's `name` property. --- @@ -967,7 +967,7 @@ lint: ### Fixes -- Resolved a hot-reloading issue with the `preview-docs` command. It will now automatically reload the docs in the browser when you make live changes to an OpenAPI definition. +- Resolved a hot-reloading issue with the `preview-docs` command. It now automatically reloads the docs in the browser when you make live changes to an OpenAPI definition. --- @@ -1015,7 +1015,7 @@ lint: ### Features -- You can now use the `--verbose` parameter with the `login` command to show a detailed error trace (if any). Detailed error output will no longer be displayed by default for this command. +- You can now use the `--verbose` parameter with the `login` command to show a detailed error trace (if any). Detailed error output is not displayed by default for this command. --- @@ -1079,7 +1079,7 @@ lint: - Resolved an issue with `assert-node-version` using the wrong path. -- OpenAPI CLI will now bundle the API definition before gathering stats. +- OpenAPI CLI bundles the API definition before gathering stats. --- @@ -1125,7 +1125,7 @@ lint: ### Features -- A new command called `stats` has been implemented. It provides statistics about the structure of one or more API definition files, and lets you choose the format in which the statistics will be presented. +- A new command called `stats` has been implemented. It provides statistics about the structure of one or more API definition files, and lets you choose the format in which the statistics are presented. ### Fixes diff --git a/docs/commands/index.md b/docs/commands/index.md index d450d635..3a0c9a37 100644 --- a/docs/commands/index.md +++ b/docs/commands/index.md @@ -50,7 +50,7 @@ Redocly CLI comes with one primary configuration file (`redocly.yaml`), also kno This file defines all of the config options available to you, including the location of your files (for unbundling and bundling), and linting rules (for validation against the OpenAPI Specification). The Redocly configuration file must sit in your root directory. -If Redocly CLI finds `redocly.yaml` in the root directory, it will use the options set in that file when executing commands. +If Redocly CLI finds `redocly.yaml` in the root directory, it uses the options set in that file when executing commands. You can also specify a config file to most commands using `--config myconfig.yaml` as part of the command. For example: diff --git a/docs/commands/join.md b/docs/commands/join.md index eb184c0d..d8cfa6a0 100644 --- a/docs/commands/join.md +++ b/docs/commands/join.md @@ -20,9 +20,9 @@ With Redocly CLI, you can solve this problem by using the `join` command that ca To easily distinguish the origin of OpenAPI objects and properties, you can optionally instruct the `join` command to append custom prefixes to them. -The `join` command accepts both YAML and JSON files, which you can mix in the resulting `openapi.yaml` file. Setting a custom name for this file can be achieved by providing it through the `--output` argument. Any existing file will be overwritten. +The `join` command accepts both YAML and JSON files, which you can mix in the resulting `openapi.yaml` file. Setting a custom name for this file can be achieved by providing it through the `--output` argument. Any existing file is overwritten. -Apart from providing individual API definition files as the input, you can also specify the path to a folder that contains multiple API definition files and match them with a wildcard (for example, `myproject/openapi/*.yaml`). The `join` command will collect all matching files and combine them into one file. +Apart from providing individual API definition files as the input, you can also specify the path to a folder that contains multiple API definition files and match them with a wildcard (for example, `myproject/openapi/*.yaml`). The `join` command collects all matching files and combines them into one file. ### Usage @@ -140,7 +140,7 @@ These options are mutually exclusive: `without-x-tag-groups`, `prefix-tags-with- ### prefix-tags-with-info-prop -If any of the input files contain the `tags` object, tags in the output file will be prefixed by the selected property from the `info` object of the corresponding input file. +If any of the input files contain the `tags` object, tags in the output file are prefixed by the selected property from the `info` object of the corresponding input file. The output file preserves the original tag names as the value of the `x-displayName` property for each tag. @@ -162,7 +162,7 @@ redocly join first-api.yaml second-api.json --prefix-tags-with-info-prop title ### prefix-tags-with-filename -If any of the input files contain the `tags` object, tags in the output file will be prefixed by the filename of the corresponding input file. +If any of the input files contain the `tags` object, tags in the output file are prefixed by the filename of the corresponding input file. The output file preserves the original tag names as the value of the `x-displayName` property for each tag. @@ -184,7 +184,7 @@ redocly join first-api.yaml second-api.json --prefix-tags-with-filename true ### without-x-tag-groups -If you have the same tags in multiple API definitions, you can allow tag duplication by using the `without-x-tag-groups` option. In this case, the `x-tagGroups` property will not be created in the joined file. +If you have the same tags in multiple API definitions, you can allow tag duplication by using the `without-x-tag-groups` option. In this case, the `x-tagGroups` property is not created in the joined file. #### Usage @@ -202,7 +202,7 @@ openapi.yaml: join processed in 69ms ### prefix-components-with-info-prop -If any of the input files have conflicting component names, this option can be used to resolve that issue and generate the output file. All component names in the output file will be prefixed by the selected property from the `info` object of the corresponding input file(s). +If any of the input files have conflicting component names, this option can be used to resolve that issue and generate the output file. All component names in the output file are prefixed by the selected property from the `info` object of the corresponding input file(s). #### Usage diff --git a/docs/commands/lint.md b/docs/commands/lint.md index 4e0a7d27..1fa3c1fc 100644 --- a/docs/commands/lint.md +++ b/docs/commands/lint.md @@ -48,7 +48,7 @@ The `lint` command behaves differently depending on how you pass apis to it and redocly lint openapi/openapi.yaml ``` -In this case, `lint` will validate the definition(s) passed to the command. The configuration file is ignored. +In this case, `lint` validates the definition(s) passed to the command. The configuration file is ignored. The `apis` argument can also use any glob format supported by your file system. For example, `redocly lint ./root-documents/*.yaml`. @@ -66,7 +66,7 @@ apis: root: ./openapi/definition.json ``` -In this case, after resolving the path behind the `core@v1` name (see the `Configuration file` tab), `lint` will validate the `definition.json` file. The presence of the Redocly configuration file is mandatory. +In this case, after resolving the path behind the `core@v1` name (see the `Configuration file` tab), `lint` validates the `definition.json` file. The presence of the Redocly configuration file is mandatory. #### Empty apis @@ -90,7 +90,7 @@ In this case, if no API definitions are specified, `lint` validates all apis lis :::warning Important -If you try to execute the `lint` command without apis when your project doesn't have any configuration files, the `lint` command will display an error. +If you try to execute the `lint` command without apis when your project doesn't have any configuration files, the `lint` command displays an error. ::: @@ -104,7 +104,7 @@ redocly lint --config=./another/directory/config.yaml ### Extend configuration -The `--extends` option allows you to extend the existing configuration. This option accepts one of the following values: `minimal`, `recommended`, `all`. Each of the values is a base set of rules that the lint command will use. You can further modify this set in cases when you want to have your own set of rules based on the existing one, including particular rules that cover your specific needs. +The `--extends` option allows you to extend the existing configuration. This option accepts one of the following values: `minimal`, `recommended`, or `all`. Each of the values is a base set of rules that the lint command uses. You can further modify this set in cases when you want to have your own set of rules based on the existing one, including particular rules that cover your specific needs. :::warning Important @@ -193,7 +193,7 @@ redocly lint --max-problems 200 ### Generate ignore file -With this option, you can generate the `.redocly.lint-ignore.yaml` file to suppress error and warning severity problems in the output. You will still receive visual feedback to let you know how many problems were ignored. +With this option, you can generate the `.redocly.lint-ignore.yaml` file to suppress error and warning severity problems in the output. You still receive visual feedback to let you know how many problems were ignored. This option is useful when you have an API design standard, but have some exceptions to the rule (for example, a legacy API operation). It allows for highly granular control. @@ -207,7 +207,7 @@ Generated ignore file with 3 problems. ``` :::warning -This command will overwrite an existing ignore file. +This command overwrites an existing ignore file. ::: To generate an ignore file for multiple definitions, pass them as arguments: diff --git a/docs/commands/login.md b/docs/commands/login.md index 60802e2d..4592ed0f 100644 --- a/docs/commands/login.md +++ b/docs/commands/login.md @@ -10,9 +10,9 @@ Before proceeding with the command, [generate a personal API key](../../settings Use the `login` command to authenticate to the API registry. -When you log in, the `preview-docs` command will start a preview server using Redocly API reference docs with all of the premium features. +When you log in, the `preview-docs` command starts a preview server using Redocly API reference docs with all of the premium features. -Also, you will be able to access your members-only (private) API definitions in the Redocly registry, and use the [`push`](./push.md) command. +Also, you can access your members-only (private) API definitions in the Redocly registry, and use the [`push`](./push.md) command. If you're having issues with the `login` command, use the `--verbose` option to display a detailed error trace (if any). diff --git a/docs/commands/preview-docs.md b/docs/commands/preview-docs.md index 1618443e..114aa374 100644 --- a/docs/commands/preview-docs.md +++ b/docs/commands/preview-docs.md @@ -4,7 +4,7 @@ With this command, you can generate documentation previews for API definitions on your local machine. -If you have a license key or API key, you will get a preview of the premium [Redocly API reference docs](https://redocly.com/reference/). If you don't, you will get a preview of [Redoc community edition](https://redocly.com/redoc/). +If you have a license key or API key configured, the output is a preview of the premium [Redocly API reference docs](https://redocly.com/reference/). Otherwise, it is a preview of [Redoc community edition](https://redocly.com/redoc/). :::success Tip To preview docs using the premium Redocly API reference docs, you must first authenticate to the API registry with the [`login`](./login.md) command. @@ -46,7 +46,7 @@ The command behaves differently depending on how you pass the api to it, and whe redocly preview-docs openapi/openapi.yaml ``` -In this case, `preview-docs` will preview the definition that was passed to the command. The configuration file is ignored. +In this case, `preview-docs` previews the definition that was passed to the command. The configuration file is ignored. #### Pass api alias @@ -86,11 +86,11 @@ redocly preview-docs -p 8888 openapi/openapi.yaml redocly preview-docs -port 8888 openapi/openapi.yaml ``` -Both commands will start the preview on port `8888`, so you can access the docs at `http://localhost:8888` +Both commands start the preview on port `8888`, so you can access the docs at `http://localhost:8888`. ### Custom host for preview -By default, without using the `host` option, the preview starts on host `127.0.0.1`, so you can access the docs at `http://127.0.0.1:8080` or `http://localhost:8080` +By default, without using the `host` option, the preview starts on host `127.0.0.1`, so you can access the docs at `http://127.0.0.1:8080` or `http://localhost:8080`. To specify a custom host for the preview, pass the desired value using either short or long option format: @@ -102,7 +102,7 @@ redocly preview-docs -h 0.0.0.0 openapi/openapi.yaml redocly preview-docs --host 0.0.0.0 openapi/openapi.yaml ``` -Both commands will start the preview on host `0.0.0.0`, so you can access the docs at `http://0.0.0.0:8080` +Both commands start the preview on host `0.0.0.0`, so you can access the docs at `http://0.0.0.0:8080` ### Skip preprocessor or decorator diff --git a/docs/commands/push.md b/docs/commands/push.md index 0a7a1770..a3668661 100644 --- a/docs/commands/push.md +++ b/docs/commands/push.md @@ -14,22 +14,22 @@ This allows you to: Apart from uploading your API definition file, the `push` command can automatically upload other files if they are detected or referenced in the API definition: - the [Redocly configuration file](/docs/cli/configuration/index.mdx) and any configuration files referenced in the `extends` list. -- the `package.json` file (if it exists) from the folder where you're executing the `push` command. Redocly Workflows will use the `@redocly/cli` version specified in `package.json`. +- the `package.json` file (if it exists) from the folder where you're executing the `push` command. Redocly Workflows uses the `@redocly/cli` version specified in `package.json`. - the HTML template and the full contents of the folder specified as the `theme > openapi > htmlTemplate` parameter in the Redocly configuration file. :::attention -If a plugin is referenced in the Redocly configuration file, the `push` command will recursively scan the folder containing the plugin and upload all `.js`, `.json`, `.mjs` and `.ts` files. +If a plugin is referenced in the Redocly configuration file, the `push` command recursively scans the folder containing the plugin and uploads all `.js`, `.json`, `.mjs` and `.ts` files. -Make sure that each plugin has all the required files in its folder, otherwise they will not be uploaded. +Make sure that each plugin has all the required files in its folder; otherwise, they are not uploaded. ::: -By default, the `push` command only updates an existing API definition version. If an API with the provided name and version doesn't exist in your organization, it will not be created automatically. For details on how to create an API, check the [Upsert an API with push](#upsert-an-api-with-push) section. +By default, the `push` command only updates an existing API definition version. If an API with the provided name and version doesn't exist in your organization, it isn't created automatically. For details on how to create an API, check the [Upsert an API with push](#upsert-an-api-with-push) section. :::warning -Only API definitions with a CI source can be updated with the `push` command. Attempting to update API definitions created from other sources will fail with an error. +Only API definitions with a CI source can be updated with the `push` command. Attempting to update API definitions created from other sources fails with an error. ::: @@ -44,7 +44,7 @@ Before using the `push` command, ensure the following prerequisites are met: To authenticate to the API registry, you can use several approaches: -- use the [`login` command](login.md). In this case, the command will look as follows: +- use the [`login` command](login.md). In this case, the command is as follows: ```bash redocly login @@ -80,8 +80,8 @@ redocly push [-u] [--batch-id id] [--batch-size number] |bundle| C(External) ``` -The following image highlights what we'll remove in this tutorial. +The following image highlights what is to be removed in this tutorial. ![what needs to be hidden](./images/hide-internal-apis-problem.png) ## Prerequisites @@ -37,9 +37,9 @@ This tutorial is most effective when you follow along and complete the steps. ## Step 1: Add `x-internal` to the API definition -In this step, you will mark operations and properties of the API definition as internal. +In this step, mark which operations and properties of the API definition are for internal use. -Open the `sample.yaml` file in your IDE. We'll change it in a few places. +Open the `sample.yaml` file in your IDE. Changes are needed in a few places. 1. Go to line 22 and add a new line between `post` and `operationId`. The indentation is important. @@ -61,7 +61,7 @@ Open the `sample.yaml` file in your IDE. We'll change it in a few places. ## Step 2: Add a Redocly configuration file -In this step, you will create a Redocly configuration file with two APIs pointing to the same root file. +In this step, create a Redocly configuration file with two APIs pointing to the same root file. Make a new file in the same `hide-apis-demo` directory named `redocly.yaml` (the casing is important). @@ -105,7 +105,7 @@ Save the `redocly.yaml` file. ## Step 3: Output internal and external APIs -In this step, you'll produce the two API snapshots from the single source of truth. +In this step, produce two API snapshots from the single source of truth. This can be done in two ways: - Option A: Let Redocly's API registry handle the work (which uses the `bundle` command under the hood). @@ -114,7 +114,7 @@ This can be done in two ways: ### Option A: Redocly's API registry bundles automatically 1. Add the APIs to the API registry. - This process will vary depending on the source type you use. + This process varies depending on the source type you use. If using the CICD `push` command, it can push all APIs or the API you specify by the API `name@version`. If using a git-based integration, select the appropriate API in the path to your root file. diff --git a/docs/guides/hide-specification-extensions.md b/docs/guides/hide-specification-extensions.md index 23532797..6f0afbcc 100644 --- a/docs/guides/hide-specification-extensions.md +++ b/docs/guides/hide-specification-extensions.md @@ -1,13 +1,13 @@ # Hide OpenAPI specification extensions When you want to hide internal operations and properties, you can follow our [hide internal APIs](./hide-apis.md) guide. -However, this approach won't work if you use [specification extensions](https://redocly.com/docs/openapi-visual-reference/specification-extensions/) +However, this approach doesn't work if you use [specification extensions](https://redocly.com/docs/openapi-visual-reference/specification-extensions/) in your API and want to hide their details as well. For this purpose, you need a custom decorator. ## Overview -In this tutorial, we'll maintain a single source of truth (SSOT) OpenAPI definition. -Then, we'll generate an internal and an external version of the API. +In this tutorial, see how to maintain a single source of truth (SSOT) OpenAPI definition. +Then generate an internal and an external version of the API. ```mermaid graph TD @@ -92,7 +92,7 @@ You can name the decorators directory anything you want. Make sure you use the c ## Step 3: Configure the plugin for use -To use the decorator, you will need to register your plugin in your Redocly configuration file `redocly.yaml`. Register your `plugins` and `decorators`. +To use the decorator, register your plugin in your Redocly configuration file `redocly.yaml`. Register your `plugins` and `decorators`. ```yaml apis: @@ -124,7 +124,7 @@ Make sure your `hide-openapi-extensions` looks as follows: ## Step 4: Output internal and external APIs -In this step, you'll produce the two API snapshots from the single source of truth. To do this, you can use the [`bundle` command](../commands/bundle.md) on your machine. +In this step, two API snapshots are produced from the single source of truth. To do this, you can use the [`bundle` command](../commands/bundle.md) on your machine. 1. Bundle the `external@latest` API. diff --git a/docs/guides/replace-servers-url.md b/docs/guides/replace-servers-url.md index 58b16f54..0e5c9d7f 100644 --- a/docs/guides/replace-servers-url.md +++ b/docs/guides/replace-servers-url.md @@ -75,7 +75,7 @@ You can name the plugins directory and file anything you want. Make sure you use ## Step 2: Add a decorator and associate it with an environment variable -In this step, you will add a decorator and define the environment variable associated with it. +In this step, add a decorator and define the environment variable associated with it. 1. Create a directory `decorators` inside of the `plugins` directory. 1. Create a `replace-servers-url.js` file with this information and save it inside of the `decorators` directory. @@ -108,7 +108,7 @@ You can name the decorators directory anything you want. Make sure you use the c ## Step 3: Configure the plugin for use -To use the decorator, you will need to register your plugin in your Redocly configuration file. Register your `plugins` and `decorators`. +To use the decorator, register your plugin in your Redocly configuration file. Register your `plugins` and `decorators`. ```yaml apis: diff --git a/docs/guides/response-contains-property.md b/docs/guides/response-contains-property.md index 481d5b49..be0c6078 100644 --- a/docs/guides/response-contains-property.md +++ b/docs/guides/response-contains-property.md @@ -19,7 +19,7 @@ Let's get started! ## Before you begin -- [Use the openapi-starter repository](../openapi-starter.md) to set up a basic project that we will use for this guide. +- [Use the openapi-starter repository](../openapi-starter.md) to set up a basic project for use with this guide. - [Download the modified project files](https://gist.github.com/bandantonio/c6047e3ee70c90da013a2f8e6757edb0) and use them to replace the corresponding files in the `openapi` folder: diff --git a/docs/guides/update-cli.md b/docs/guides/update-cli.md index a7b9cc64..20920dae 100644 --- a/docs/guides/update-cli.md +++ b/docs/guides/update-cli.md @@ -5,7 +5,7 @@ redirectFrom: # Update Redocly CLI -If you've already installed Redocly CLI, you'll want to keep it as up to date as possible. Staying on top of versions ensures that you get the latest functionality and bug fixes. +If you've already installed Redocly CLI, it is good practice to keep it as up to date as possible. Staying on top of versions ensures that you get the latest functionality and bug fixes. If you [installed Redocly CLI globally](../installation.md), run this command: diff --git a/docs/index.md b/docs/index.md index f9991363..e6de2063 100644 --- a/docs/index.md +++ b/docs/index.md @@ -20,7 +20,7 @@ Redocly CLI is an open source command-line tool for working with OpenAPI descrip Redoc is our open source API documentation tool. Use `redocly` (this project) to work with your Redoc documentation projects. -The Redocly CLI also supports many of the other operations you'll need to be successful working with OpenAPI. API linting, enhancement, bundling and other tools are also available as part of this open source CLI tool. +The Redocly CLI also supports many of the other operations needed to be successful working with OpenAPI. API linting, enhancement, bundling and other tools are also available as part of this open source CLI tool. Redocly offers a full suite of API lifecycle tools as commercial offerings; you can manage those from this tool too. diff --git a/docs/installation.md b/docs/installation.md index 3ff50a55..820a4998 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -20,11 +20,11 @@ npm i -g @redocly/cli@latest yarn global add @redocly/cli ``` -Running `redocly --version` will confirm that the installation was successful, and the currently-installed version of the tool. +Running `redocly --version` confirms that the installation was successful, and the currently-installed version of the tool. ## Use `npx` at runtime -[npx](https://docs.npmjs.com/cli/v9/commands/npx/) is npm's package runner. It will install and run a command without installing it globally. You might use this where you can't install a new command, or in a CI context where the command is only used a handful of times. +[npx](https://docs.npmjs.com/cli/v9/commands/npx/) is npm's package runner. It installs and runs a command without installing it globally. You might use this where you can't install a new command, or in a CI context where the command is only used a handful of times. ```shell Command npx @redocly/cli [options] diff --git a/docs/openapi-starter.md b/docs/openapi-starter.md index d15e9955..558489ef 100644 --- a/docs/openapi-starter.md +++ b/docs/openapi-starter.md @@ -24,7 +24,7 @@ Clone the project to your local machine so you can use it with [Redocly CLI](qui ## Step 3: Work with OpenAPI -By default, you will have a root directory (`openapi`) that contains a sample API definition file (`openapi.yaml`). The sample file is already split into its constituent parts, which are contained in the `code_samples`, `components` and `paths` folders. +By default, there is a root directory (`openapi`) that contains a sample API definition file (`openapi.yaml`). The sample file is already split into its constituent parts, which are contained in the `code_samples`, `components` and `paths` folders. ### Just starting out with API docs? @@ -34,4 +34,4 @@ Use our `openapi.yaml` file to explore Redocly CLI. We suggest you [run some bas You can add your files straight into the `openapi` folder and use the existing sub-folders when splitting them up for easier maintenance (`split` command) and compiling them back into a single file (`bundle`) for publishing out. Be aware that the more definitions stored in the `openapi` folder, the more cluttered the sub-folders. But hey, if you like clutter then go for it! -Prefer things more orderly? Create new root folders to store each definition. When you run the `split` command in Redocly CLI for a specified definition file, the sub-folders will automatically be created under the root and populated with the constituent parts of your main definition file. +Prefer things more orderly? Create new root folders to store each definition. When you run the `split` command in Redocly CLI for a specified definition file, the sub-folders are automatically created under the root and populated with the constituent parts of your main definition file. diff --git a/docs/resources/custom-plugins.md b/docs/resources/custom-plugins.md index 41f13ef6..fd16205c 100644 --- a/docs/resources/custom-plugins.md +++ b/docs/resources/custom-plugins.md @@ -13,7 +13,7 @@ Redocly recommends using the highly [configurable rules](../rules/configurable-r ## Concepts Extend the CLI through the use of custom plugins. -There are three main differences between preprocessors, rules and decorators. +There are three main differences between preprocessors, rules, and decorators. 1. The order of execution: @@ -29,7 +29,7 @@ There are three main differences between preprocessors, rules and decorators. 1. Preprocessors and decorators do not support nested visitors. ### Plugins -A plugin defines a configuration and set of rules, preprocessors and decorators. +A plugin defines a configuration and set of rules, preprocessors, and decorators. Plugins need to be explicitly defined in the configuration file (except for the Redocly built in plugins). @@ -90,12 +90,12 @@ See an example of a custom rule implementation in our ["Response contains proper Keys of the object can be any of the following: -- node type - visitor will be called on specific node type. List of available node types for each specific OAS version: +- node type - the visitor is called on specific node types. List of available node types for each specific OAS version: - OAS 3.1: https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/types/oas3_1.ts#L209 - OAS 3.0: https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/types/oas3.ts#L530 - OAS 2.0: https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/types/oas2.ts#L367 -- `any` - visitor will be called on every node -- `ref` - visitor will be called on $ref nodes +- `any` - visitor is called on every node. +- `ref` - visitor is called on $ref nodes. The value of each node can be either **visitor function** (runs while going down the tree) or **visitor object** (see below). @@ -128,7 +128,9 @@ Also, visitor object (if it is not `any` or `ref`) can define [nested visitors]( ## Visitors execution and $ref -Top level **visitor functions** run only once for each node. If the same node is referenced via $ref multiple times top-level **visitor functions** will be executed only once for this node. +Top level **visitor functions** run only once for each node. +If the same node is referenced by the $ref multiple times, +top-level **visitor functions** are executed only once for this node. This works fine for most context-free rules which check basic things. If you need contextual info you should use [nested visitors](#nested-visitors). @@ -151,7 +153,7 @@ function ExampleRule() { } ``` -The `Schema` **visitor function** will be called by Redocly CLI if only Schema Object is encountered while traversing a tree while the Operation Object is **entered**. +The `Schema` **visitor function** is called by Redocly CLI only if the Schema Object is encountered while traversing a tree while the Operation Object is **entered**. As the third argument, the **visitor function** accepts the `parents` object with corresponding parent nodes as defined in the **visitor object**. @@ -184,7 +186,7 @@ put: type: number ``` -The visitor above will log the following: +The visitor above logs the following: ``` type string from get @@ -226,7 +228,7 @@ and the following methods: ## context.report() -The main method you'll use is `context.report()`, which publishes a warning or error (depending on the configuration being used). This method accepts a single argument, which is an object containing the following properties: +The main method used is `context.report()`, which publishes a warning or error (depending on the configuration being used). This method accepts a single argument, which is an object containing the following properties: - `message` - {string} the problem message. - `location` - {Location} (optional) an object specifying the location of the problem. Can be constructed using location object methods. @@ -392,7 +394,7 @@ The type tree is built from top level `Types` which can link to child types. This tree can be extended or modified. -## Extending type definitions +## Extend type definitions The type tree can be extended by exporting the `typeExtension` function from a custom plugin. Follow this pattern (similar to reducers if you're familiar with the map-reduce pattern): diff --git a/docs/rules.md b/docs/rules.md index e8e0b450..1e7db052 100644 --- a/docs/rules.md +++ b/docs/rules.md @@ -39,4 +39,4 @@ Severity settings determine how the rule is treated during the validation proces ## Rule ideas Redocly CLI supports [custom rules](./rules/configurable-rules.md) and [custom plugins](./resources/custom-plugins.md). -However, if you have an idea for a built-in rule you believe will benefit the greater API community, please [open an issue](https://github.com/Redocly/redocly-cli/issues/new) in the Redocly CLI repository. +However, if you have an idea for a built-in rule you believe benefits the greater API community, please [open an issue](https://github.com/Redocly/redocly-cli/issues/new) in the Redocly CLI repository. diff --git a/docs/rules/info-license-url.md b/docs/rules/info-license-url.md index 4d3ee878..7f7b1535 100644 --- a/docs/rules/info-license-url.md +++ b/docs/rules/info-license-url.md @@ -23,9 +23,7 @@ The principle of providing your users with accurate and relevant information doe Before they can work with your API, your users must understand the terms and conditions of your API usage. -"Can I use your API? Will I get in trouble? Will I lose my job?" -Sometimes questions like these go through consumers' minds. -By being upfront with the API license, you can reduce friction towards usage. +By being upfront with the API license, you can reduce friction and encourage API adoption. ## Configuration diff --git a/docs/rules/info-license.md b/docs/rules/info-license.md index 099303b5..efd6e796 100644 --- a/docs/rules/info-license.md +++ b/docs/rules/info-license.md @@ -23,9 +23,7 @@ The principle of providing your users with accurate and relevant information doe Before they can work with your API, your users must understand the terms and conditions of your API usage. -"Can I use your API? Will I get in trouble? Will I lose my job?" -Sometimes questions like these go through consumers' minds. -By being upfront with the API license, you can reduce friction towards usage. +By being upfront with the API license, you can reduce friction and encourage API adoption. ## Configuration diff --git a/docs/rules/no-http-verbs-in-paths.md b/docs/rules/no-http-verbs-in-paths.md index b3822241..2f081141 100644 --- a/docs/rules/no-http-verbs-in-paths.md +++ b/docs/rules/no-http-verbs-in-paths.md @@ -34,9 +34,10 @@ The REST type prefers to name paths after resources like "customers", and "payme And the REST type relies on HTTP methods, like GET, to indicate the action on that resource. It would be considered a design fail to make the path "getcustomers" or "get-customers" or any variation on that. If you're aiming to design RESTful resources, then consider this rule your friend. -There is the option to `splitIntoWords` to reduce false positives. + +To reduce false positives, use the `splitIntoWords` option. Imagine a world-famous rock band, the Redockers, and they have an API powering their music tour with one resource "posters". -With the `splitIntoWords` enabled it will be identified as a resource and not trigger a false positive even though it contains the word `post`. +With the `splitIntoWords` option enabled, "posters" is identified as a resource and does not trigger a false positive, even though it contains the word `post`. ## Configuration @@ -113,7 +114,7 @@ paths: $ref: ./paths/customer.yaml ``` -This last example wouldn't trigger an error because the casing won't split "get" into its own word. +This last example wouldn't trigger an error because the casing doesn't split "get" into its own word. ## Related rules diff --git a/docs/rules/operation-description.md b/docs/rules/operation-description.md index 55386ae5..725e9919 100644 --- a/docs/rules/operation-description.md +++ b/docs/rules/operation-description.md @@ -13,13 +13,7 @@ Requires the `description` field for every operation in your API. Every operation should have a description to help your API consumers understand what it does and how to use it. Without a description, people who want to use your API have to guess what an operation does, or try to decipher it from other parts of your API definition, or from other documentation and external resources that may not be accurate. Your API definition should be the single source of truth about your API. - -Okay, so we're documentation folks here. -You're thinking, "of course they would say that." -You're right! -And we're right! -Do this, and your (future) teammates will thank you. -Do this, and your API consumers will thank you. +Add the description field and delight both your (future) teammates and your API consumers. ## Configuration diff --git a/docs/rules/path-segment-plural.md b/docs/rules/path-segment-plural.md index 97e4e70d..97a0cf7d 100644 --- a/docs/rules/path-segment-plural.md +++ b/docs/rules/path-segment-plural.md @@ -18,7 +18,7 @@ For example, "customers" instead of "customer" because: - `GET /customers` means getting a collection of customers - `GET /customers/abc` means getting customer ABC from the customers collection -As your API grows, you'll likely hit some false positives and may also need to ignore a few outliers. +As your API grows, you may hit some false positives and may also need to ignore a few outliers. That is, unless you're a purist. Nothing wrong with that.