diff --git a/.changeset/free-fans-march.md b/.changeset/free-fans-march.md new file mode 100644 index 0000000000..b59774d3a6 --- /dev/null +++ b/.changeset/free-fans-march.md @@ -0,0 +1,6 @@ +--- +"@redocly/cli": patch +"@redocly/openapi-core": patch +--- + +Add linting guides for OpenAPI Overlay. diff --git a/docs/@v1/guides/lint-overlay.md b/docs/@v1/guides/lint-overlay.md new file mode 100644 index 0000000000..cf8d5c69a1 --- /dev/null +++ b/docs/@v1/guides/lint-overlay.md @@ -0,0 +1,126 @@ +--- +seo: + title: Lint Overlay with Redocly CLI + description: Unlock powerful linting capabilities for Overlay documents. Use the Redocly CLI to enforce basic validation, configure rules, or even build custom plugins for Overlay. +--- + +# Lint Overlay with Redocly CLI + +[Overlay](https://spec.openapis.org/overlay/latest.html#Overlay-specification) is an open standard from the OpenAPI Initiative for describing a set of changes to be applied or “overlaid” onto an existing OpenAPI description. +Redocly CLI offers support for checking that your Overlay files are valid. + +{% admonition type="info" name="Experimental Overlay support" %} +This feature is at an early stage, please send us lots of [feedback](https://github.com/redocly/redocly-cli/issues)! +{% /admonition %} + +## Lint an Overlay file + +Use your existing Overlay files, or use the Overlay examples in the [Museum API project](https://github.com/Redocly/museum-openapi-example) if you'd prefer to use sample data to try things out. + +**Pro-tip:** linting is much more interesting if the file actually does contain problems. +Be your own chaos monkey and introduce some errors before you proceed! + +Lint using a command like the following: + +```bash +redocly lint overlay/museum-api.overlay.yaml +``` + +If the file does not match the specification, the tool shows the details of each error that it finds, like in the following example: + +```text +validating overlay/museum-api.overlay.yaml... +[1] overlay/museum-api.overlay.yaml:5:3 at #/info/description + +Property `description` is not expected here. + +3 | title: Sample Overlay Configuration +4 | version: 1.0.0 +5 | description: "" +6 | extends: openapi.yaml +7 | actions: + +Error was generated by the struct rule. + + + +validating overlay/museum-api.overlay.yaml... +[1] overlay/museum-api.overlay.yaml:11:3 at #/actions/1/descript + +Property `descript` is not expected here. + +Did you mean: description ? + +10 | - target: $.paths['/museum-hours'] +11 | descript: "not a valid field(misspelled)" +12 | remove: true + +Error was generated by the struct rule. + +``` + +## Configure the linting rules + +Choose from the ready-made rulesets (`minimal`, `recommended` or `recommended-strict`), or go one better and configure the rules that suit your use case. +There's a full [list of built-in rules for Overlay](../rules/built-in-rules.md#Overlay-rules) to refer to. + +Add the rules to `redocly.yaml`, but for Overlay specifications. +The following example shows configuration for the minimal ruleset with additional rules configuration: + +```yaml +extends: + - minimal + +rules: + info-contact: warn +``` + +The configuration shown here gives some good entry-level linting using the `minimal` standard, and warns if info contact information is missing. + +## Choose output format + +Since Redocly CLI is already a fully-featured lint tool, additional features such as a choice of formats are already included. + +Get a report in **Markdown format** with the following command: + +```bash +redocly lint --format=markdown overlay/museum-api.overlay.yaml +``` + +Choose your preferred output format from `codeframe`, `stylish`, `json`, `checkstyle`, `codeclimate`, `github-actions`, `markdown`, or `summary`. +The [lint command page](../commands/lint.md) has full details of the command's options. + +## Add Overlay linting to GitHub Actions + +To make sure that your Overlay description remains valid, add linting to your CI (Continuous Integration) setup. +You can use Redocly CLI with the `github-actions` output format to get annotations directly in your pull request if any validation problems are found. +The following snippet shows an example of configuring a GitHub action for linting: + +```yaml +name: Validate museum overlay descriptions + +on: [pull_request] + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Set up node + uses: actions/setup-node@v4 + - name: Install Redocly CLI + run: npm install -g @redocly/cli@latest + - name: Run linting + run: redocly lint overlay/*yaml --format=github-actions +``` + +With this action in place, the intentional errors I added to the Overlay description are shown as annotations on the pull request: + + + +![Screenshot of annotation flagging "description" as an unexpected value](images/museum-overlay-lint.png) + +## Participate in Redocly CLI + +Redocly CLI is an open source project, so we invite you to check out the [code on GitHub](https://github.com/Redocly/redocly-cli/), and open issues to report problems or request features. diff --git a/docs/@v1/rules/arazzo/struct.md b/docs/@v1/rules/arazzo/struct.md index ad47ed3153..cb56b67e34 100644 --- a/docs/@v1/rules/arazzo/struct.md +++ b/docs/@v1/rules/arazzo/struct.md @@ -12,7 +12,7 @@ Ensures that your API document conforms to the [OpenAPI specification](https://s The default setting for this rule (in the `recommended` and `minimal` configuration) is `error`. -This is an essential rule. Do not turned it off, except in rare and special cases. +This is an essential rule. Do not turn it off, except in rare and special cases. ## Configuration diff --git a/docs/@v1/rules/built-in-rules.md b/docs/@v1/rules/built-in-rules.md index 294d17c64f..9b1b41e315 100644 --- a/docs/@v1/rules/built-in-rules.md +++ b/docs/@v1/rules/built-in-rules.md @@ -138,6 +138,15 @@ The below rules are being migrated to Respect: - [no-criteria-xpath](./respect/no-criteria-xpath.md): the `xpath` type criteria is not supported by Respect. - [respect-supported-versions](./respect/respect-supported-versions.md): the `version` property must be one of the supported values. +## Overlay rules + +Rules for the main Overlay specification format. + +### Overlay + +- [info-contact](./overlay/info-contact.md): Contact section is defined under `info` +- [no-unresolved-refs](./oas/no-unresolved-refs.md): Every `$ref` must exist + ## Resources - Learn more about [API linting](../api-standards.md), or follow the [guide to configuring a ruleset](../guides/configure-rules.md). diff --git a/docs/@v1/rules/overlay/info-contact.md b/docs/@v1/rules/overlay/info-contact.md new file mode 100644 index 0000000000..58676f61b7 --- /dev/null +++ b/docs/@v1/rules/overlay/info-contact.md @@ -0,0 +1,74 @@ +--- +slug: /docs/cli/v1/rules/overlay/info-contact +--- + +# info-contact + +Requires the `Contact` info object defined in your API. + +| Overlay | Compatibility | +| ------- | ------------- | +| 1.0 | ✅ | + +```mermaid +flowchart TD + +Root ==> Info --> Contact + +style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px +``` + +## API design principles + +When it comes to APIs, we generally want more consumers. +If they need help to purchase, integrate, or troubleshoot, your contact info should be front and center. + +## Configuration + +| Option | Type | Description | +| -------- | ------ | ------------------------------------------------------- | +| severity | string | Possible values: `off`, `warn`, `error`. Default `off`. | + +An example configuration: + +```yaml +rules: + info-contact: warn +``` + +## Examples + +Given this configuration: + +```yaml +rules: + info-contact: error +``` + +Example of **incorrect** contact: + +```yaml Incorrect example +info: + version: 1.0.0 + title: Incorrect example missing contact +``` + +Example of **correct** contact: + +```yaml Correct example +info: + contact: + name: Redocly API Support + url: https://www.redocly.com/support + email: team@redocly.com +``` + +## Related rules + +- [spec](./struct.md) +- [configurable rules](../configurable-rules.md) + +## Resources + +- [Rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/common/info-contact.ts) +- [Contact object docs](https://redocly.com/docs/openapi-visual-reference/contact/) diff --git a/docs/@v1/rules/overlay/struct.md b/docs/@v1/rules/overlay/struct.md new file mode 100644 index 0000000000..ac85f42d08 --- /dev/null +++ b/docs/@v1/rules/overlay/struct.md @@ -0,0 +1,28 @@ +--- +slug: /docs/cli/v1/rules/overlay/struct +--- + +# struct + +Ensures that your API document conforms to the [Overlay specification](https://spec.openapis.org/overlay/latest.html#Overlay-specification). + +| Overlay | Compatibility | +| ------- | ------------- | +| 1.x | ✅ | + +The default setting for this rule (in the `recommended` and `minimal` configuration) is `error`. + +This is an essential rule. Do not turn it off, except in rare and special cases. + +## Configuration + +| Option | Type | Description | +| -------- | ------ | ------------------------------------------------------------------------------------------ | +| severity | string | Possible values: `off`, `warn`, `error`. Default `error` (in `recommended` configuration). | + +An example configuration: + +```yaml +rules: + struct: error +``` diff --git a/docs/@v2/guides/lint-overlay.md b/docs/@v2/guides/lint-overlay.md new file mode 100644 index 0000000000..cf8d5c69a1 --- /dev/null +++ b/docs/@v2/guides/lint-overlay.md @@ -0,0 +1,126 @@ +--- +seo: + title: Lint Overlay with Redocly CLI + description: Unlock powerful linting capabilities for Overlay documents. Use the Redocly CLI to enforce basic validation, configure rules, or even build custom plugins for Overlay. +--- + +# Lint Overlay with Redocly CLI + +[Overlay](https://spec.openapis.org/overlay/latest.html#Overlay-specification) is an open standard from the OpenAPI Initiative for describing a set of changes to be applied or “overlaid” onto an existing OpenAPI description. +Redocly CLI offers support for checking that your Overlay files are valid. + +{% admonition type="info" name="Experimental Overlay support" %} +This feature is at an early stage, please send us lots of [feedback](https://github.com/redocly/redocly-cli/issues)! +{% /admonition %} + +## Lint an Overlay file + +Use your existing Overlay files, or use the Overlay examples in the [Museum API project](https://github.com/Redocly/museum-openapi-example) if you'd prefer to use sample data to try things out. + +**Pro-tip:** linting is much more interesting if the file actually does contain problems. +Be your own chaos monkey and introduce some errors before you proceed! + +Lint using a command like the following: + +```bash +redocly lint overlay/museum-api.overlay.yaml +``` + +If the file does not match the specification, the tool shows the details of each error that it finds, like in the following example: + +```text +validating overlay/museum-api.overlay.yaml... +[1] overlay/museum-api.overlay.yaml:5:3 at #/info/description + +Property `description` is not expected here. + +3 | title: Sample Overlay Configuration +4 | version: 1.0.0 +5 | description: "" +6 | extends: openapi.yaml +7 | actions: + +Error was generated by the struct rule. + + + +validating overlay/museum-api.overlay.yaml... +[1] overlay/museum-api.overlay.yaml:11:3 at #/actions/1/descript + +Property `descript` is not expected here. + +Did you mean: description ? + +10 | - target: $.paths['/museum-hours'] +11 | descript: "not a valid field(misspelled)" +12 | remove: true + +Error was generated by the struct rule. + +``` + +## Configure the linting rules + +Choose from the ready-made rulesets (`minimal`, `recommended` or `recommended-strict`), or go one better and configure the rules that suit your use case. +There's a full [list of built-in rules for Overlay](../rules/built-in-rules.md#Overlay-rules) to refer to. + +Add the rules to `redocly.yaml`, but for Overlay specifications. +The following example shows configuration for the minimal ruleset with additional rules configuration: + +```yaml +extends: + - minimal + +rules: + info-contact: warn +``` + +The configuration shown here gives some good entry-level linting using the `minimal` standard, and warns if info contact information is missing. + +## Choose output format + +Since Redocly CLI is already a fully-featured lint tool, additional features such as a choice of formats are already included. + +Get a report in **Markdown format** with the following command: + +```bash +redocly lint --format=markdown overlay/museum-api.overlay.yaml +``` + +Choose your preferred output format from `codeframe`, `stylish`, `json`, `checkstyle`, `codeclimate`, `github-actions`, `markdown`, or `summary`. +The [lint command page](../commands/lint.md) has full details of the command's options. + +## Add Overlay linting to GitHub Actions + +To make sure that your Overlay description remains valid, add linting to your CI (Continuous Integration) setup. +You can use Redocly CLI with the `github-actions` output format to get annotations directly in your pull request if any validation problems are found. +The following snippet shows an example of configuring a GitHub action for linting: + +```yaml +name: Validate museum overlay descriptions + +on: [pull_request] + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Set up node + uses: actions/setup-node@v4 + - name: Install Redocly CLI + run: npm install -g @redocly/cli@latest + - name: Run linting + run: redocly lint overlay/*yaml --format=github-actions +``` + +With this action in place, the intentional errors I added to the Overlay description are shown as annotations on the pull request: + + + +![Screenshot of annotation flagging "description" as an unexpected value](images/museum-overlay-lint.png) + +## Participate in Redocly CLI + +Redocly CLI is an open source project, so we invite you to check out the [code on GitHub](https://github.com/Redocly/redocly-cli/), and open issues to report problems or request features. diff --git a/docs/@v2/rules/built-in-rules.md b/docs/@v2/rules/built-in-rules.md index 006434c285..e557600c91 100644 --- a/docs/@v2/rules/built-in-rules.md +++ b/docs/@v2/rules/built-in-rules.md @@ -149,6 +149,15 @@ The below rules are being migrated to Respect: - [x-security-scheme-name-reference](./respect/x-security-scheme-name-reference.md): when multiple `sourceDescriptions` exist, `workflow.x-security.schemeName` must reference a source description (for example, `$sourceDescriptions.{name}.schemeName`) - [x-security-scheme-required-values](./respect/x-security-scheme-required-values.md) validate that `x-security` have all required `values` described according to the used `scheme`. +## Overlay rules + +Rules for the main Overlay specification format. + +### Overlay + +- [info-contact](./overlay/info-contact.md): Contact section is defined under `info` +- [no-unresolved-refs](./common/no-unresolved-refs.md): Every `$ref` must exist + ## Open-RPC rules Use the rules in this section for Open-RPC specific linting. diff --git a/docs/@v2/rules/overlay/info-contact.md b/docs/@v2/rules/overlay/info-contact.md new file mode 100644 index 0000000000..14624bcb7d --- /dev/null +++ b/docs/@v2/rules/overlay/info-contact.md @@ -0,0 +1,74 @@ +--- +slug: /docs/cli/v2/rules/overlay/info-contact +--- + +# info-contact + +Requires the `Contact` info object defined in your API. + +| Overlay | Compatibility | +| ------- | ------------- | +| 1.0 | ✅ | + +```mermaid +flowchart TD + +Root ==> Info --> Contact + +style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px +``` + +## API design principles + +When it comes to APIs, we generally want more consumers. +If they need help to purchase, integrate, or troubleshoot, your contact info should be front and center. + +## Configuration + +| Option | Type | Description | +| -------- | ------ | ------------------------------------------------------- | +| severity | string | Possible values: `off`, `warn`, `error`. Default `off`. | + +An example configuration: + +```yaml +rules: + info-contact: warn +``` + +## Examples + +Given this configuration: + +```yaml +rules: + info-contact: error +``` + +Example of **incorrect** contact: + +```yaml Incorrect example +info: + version: 1.0.0 + title: Incorrect example missing contact +``` + +Example of **correct** contact: + +```yaml Correct example +info: + contact: + name: Redocly API Support + url: https://www.redocly.com/support + email: team@redocly.com +``` + +## Related rules + +- [spec](./struct.md) +- [configurable rules](../configurable-rules.md) + +## Resources + +- [Rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/common/info-contact.ts) +- [Contact object docs](https://redocly.com/docs/openapi-visual-reference/contact/) diff --git a/docs/@v2/rules/overlay/struct.md b/docs/@v2/rules/overlay/struct.md new file mode 100644 index 0000000000..ac85f42d08 --- /dev/null +++ b/docs/@v2/rules/overlay/struct.md @@ -0,0 +1,28 @@ +--- +slug: /docs/cli/v1/rules/overlay/struct +--- + +# struct + +Ensures that your API document conforms to the [Overlay specification](https://spec.openapis.org/overlay/latest.html#Overlay-specification). + +| Overlay | Compatibility | +| ------- | ------------- | +| 1.x | ✅ | + +The default setting for this rule (in the `recommended` and `minimal` configuration) is `error`. + +This is an essential rule. Do not turn it off, except in rare and special cases. + +## Configuration + +| Option | Type | Description | +| -------- | ------ | ------------------------------------------------------------------------------------------ | +| severity | string | Possible values: `off`, `warn`, `error`. Default `error` (in `recommended` configuration). | + +An example configuration: + +```yaml +rules: + struct: error +```