Skip to content

Commit 6ced875

Browse files
jeremyfieljeremyfiel
committed
feat(docs): add Overlay linting guides
updates #1830
1 parent cb9aba3 commit 6ced875

File tree

9 files changed

+480
-0
lines changed

9 files changed

+480
-0
lines changed

‎.changeset/free-fans-march.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
"@redocly/cli": patch
3+
"@redocly/openapi-core": patch
4+
---
5+
6+
Add Overlay linting guides.

‎docs/@v1/guides/lint-overlay.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
---
2+
seo:
3+
title: Lint Overlay with Redocly CLI
4+
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.
5+
---
6+
7+
# Lint Overlay with Redocly CLI
8+
9+
[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.
10+
Redocly CLI offers support for checking that your Overlay files are valid.
11+
12+
{% admonition type="info" name="Experimental Overlay support" %}
13+
This feature is at an early stage, please send us lots of [feedback](https://github.com/redocly/redocly-cli/issues)!
14+
{% /admonition %}
15+
16+
## Lint an Overlay file
17+
18+
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.
19+
20+
**Pro-tip:** linting is much more interesting if the file actually does contain problems.
21+
Be your own chaos monkey and introduce some errors before you proceed!
22+
23+
Lint using a command like the following:
24+
25+
```bash
26+
redocly lint overlay/museum-api.overlay.yaml
27+
```
28+
29+
If the file does not match the specification, the tool shows the details of each error that it finds, like in the following example:
30+
31+
```text
32+
validating overlay/museum-api.overlay.yaml...
33+
[1] overlay/museum-api.overlay.yaml:5:3 at #/info/description
34+
35+
Property `description` is not expected here.
36+
37+
3 | title: Sample Overlay Configuration
38+
4 | version: 1.0.0
39+
5 | description: ""
40+
6 | extends: openapi.yaml
41+
7 | actions:
42+
43+
Error was generated by the struct rule.
44+
45+
46+
47+
validating overlay/museum-api.overlay.yaml...
48+
[1] overlay/museum-api.overlay.yaml:11:3 at #/actions/1/descript
49+
50+
Property `descript` is not expected here.
51+
52+
Did you mean: description ?
53+
54+
10 | - target: $.paths['/museum-hours']
55+
11 | descript: "not a valid field(misspelled)"
56+
12 | remove: true
57+
58+
Error was generated by the struct rule.
59+
60+
```
61+
62+
## Configure the linting rules
63+
64+
Choose from the ready-made rulesets (`minimal`, `recommended` or `recommended-strict`), or go one better and configure the rules that suit your use case.
65+
There's a full [list of built-in rules for Overlay](../rules/built-in-rules.md#Overlay-rules) to refer to.
66+
67+
Add the rules to `redocly.yaml`, but for Overlay specifications.
68+
The following example shows configuration for the minimal ruleset with additional rules configuration:
69+
70+
```yaml
71+
extends:
72+
- minimal
73+
74+
rules:
75+
info-contact: warn
76+
```
77+
78+
The configuration shown here gives some good entry-level linting using the `minimal` standard, and warns if info contact information is missing.
79+
80+
## Choose output format
81+
82+
Since Redocly CLI is already a fully-featured lint tool, additional features such as a choice of formats are already included.
83+
84+
Get a report in **Markdown format** with the following command:
85+
86+
```bash
87+
redocly lint --format=markdown overlay/museum-api.overlay.yaml
88+
```
89+
90+
Choose your preferred output format from `codeframe`, `stylish`, `json`, `checkstyle`, `codeclimate`, `github-actions`, `markdown`, or `summary`.
91+
The [lint command page](../commands/lint.md) has full details of the command's options.
92+
93+
## Add Overlay linting to GitHub Actions
94+
95+
To make sure that your Overlay description remains valid, add linting to your CI (Continuous Integration) setup.
96+
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.
97+
The following snippet shows an example of configuring a GitHub action for linting:
98+
99+
```yaml
100+
name: Validate museum overlay descriptions
101+
102+
on: [pull_request]
103+
104+
jobs:
105+
build:
106+
runs-on: ubuntu-latest
107+
steps:
108+
- name: Checkout
109+
uses: actions/checkout@v4
110+
- name: Set up node
111+
uses: actions/setup-node@v4
112+
- name: Install Redocly CLI
113+
run: npm install -g @redocly/cli@latest
114+
- name: Run linting
115+
run: redocly lint overlay/*yaml --format=github-actions
116+
```
117+
118+
With this action in place, the intentional errors I added to the Overlay description are shown as annotations on the pull request:
119+
120+
<!-- TODO: Replace with actual image link -->
121+
122+
![Screenshot of annotation flagging "description" as an unexpected value](images/museum-overlay-lint.png)
123+
124+
## Participate in Redocly CLI
125+
126+
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.

‎docs/@v1/rules/built-in-rules.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -138,6 +138,15 @@ The below rules are being migrated to Respect:
138138
- [no-criteria-xpath](./respect/no-criteria-xpath.md): the `xpath` type criteria is not supported by Respect.
139139
- [respect-supported-versions](./respect/respect-supported-versions.md): the `version` property must be one of the supported values.
140140

141+
## Overlay rules
142+
143+
Rules for the main Overlay specification format.
144+
145+
### Overlay
146+
147+
- [info-contact](./overlay/info-contact.md): Contact section is defined under `info`
148+
- [no-unresolved-refs](./oas/no-unresolved-refs.md): Every `$ref` must exist
149+
141150
## Resources
142151

143152
- Learn more about [API linting](../api-standards.md), or follow the [guide to configuring a ruleset](../guides/configure-rules.md).

‎docs/@v1/rules/overlay/info-contact.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
---
2+
slug: /docs/cli/v1/rules/overlay/info-contact
3+
---
4+
5+
# info-contact
6+
7+
Requires the `Contact` info object defined in your API.
8+
9+
| Overlay | Compatibility |
10+
| ------- | ------------- |
11+
| 1.0 | ✅ |
12+
13+
```mermaid
14+
flowchart TD
15+
16+
Root ==> Info --> Contact
17+
18+
style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px
19+
```
20+
21+
## API design principles
22+
23+
When it comes to APIs, we generally want more consumers.
24+
If they need help to purchase, integrate, or troubleshoot, your contact info should be front and center.
25+
26+
## Configuration
27+
28+
| Option | Type | Description |
29+
| -------- | ------ | ------------------------------------------------------- |
30+
| severity | string | Possible values: `off`, `warn`, `error`. Default `off`. |
31+
32+
An example configuration:
33+
34+
```yaml
35+
rules:
36+
info-contact: warn
37+
```
38+
39+
## Examples
40+
41+
Given this configuration:
42+
43+
```yaml
44+
rules:
45+
info-contact: error
46+
```
47+
48+
Example of **incorrect** contact:
49+
50+
```yaml Incorrect example
51+
info:
52+
version: 1.0.0
53+
title: Incorrect example missing contact
54+
```
55+
56+
Example of **correct** contact:
57+
58+
```yaml Correct example
59+
info:
60+
contact:
61+
name: Redocly API Support
62+
url: https://www.redocly.com/support
63+
email: [email protected]
64+
```
65+
66+
## Related rules
67+
68+
- [spec](./struct.md)
69+
- [configurable rules](../configurable-rules.md)
70+
71+
## Resources
72+
73+
- [Rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/common/info-contact.ts)
74+
- [Contact object docs](https://redocly.com/docs/openapi-visual-reference/contact/)

‎docs/@v1/rules/overlay/struct.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
slug: /docs/cli/v1/rules/overlay/struct
3+
---
4+
5+
# struct
6+
7+
Ensures that your API document conforms to the [Overlay specification](https://spec.openapis.org/overlay/latest.html#Overlay-specification).
8+
9+
| Overlay | Compatibility |
10+
| ------- | ------------- |
11+
| 1.x | ✅ |
12+
13+
The default setting for this rule (in the `recommended` and `minimal` configuration) is `error`.
14+
15+
This is an essential rule. Do not turned it off, except in rare and special cases.
16+
17+
## Configuration
18+
19+
| Option | Type | Description |
20+
| -------- | ------ | ------------------------------------------------------------------------------------------ |
21+
| severity | string | Possible values: `off`, `warn`, `error`. Default `error` (in `recommended` configuration). |
22+
23+
An example configuration:
24+
25+
```yaml
26+
rules:
27+
struct: error
28+
```

‎docs/@v2/guides/lint-overlay.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
---
2+
seo:
3+
title: Lint Overlay with Redocly CLI
4+
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.
5+
---
6+
7+
# Lint Overlay with Redocly CLI
8+
9+
[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.
10+
Redocly CLI offers support for checking that your Overlay files are valid.
11+
12+
{% admonition type="info" name="Experimental Overlay support" %}
13+
This feature is at an early stage, please send us lots of [feedback](https://github.com/redocly/redocly-cli/issues)!
14+
{% /admonition %}
15+
16+
## Lint an Overlay file
17+
18+
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.
19+
20+
**Pro-tip:** linting is much more interesting if the file actually does contain problems.
21+
Be your own chaos monkey and introduce some errors before you proceed!
22+
23+
Lint using a command like the following:
24+
25+
```bash
26+
redocly lint overlay/museum-api.overlay.yaml
27+
```
28+
29+
If the file does not match the specification, the tool shows the details of each error that it finds, like in the following example:
30+
31+
```text
32+
validating overlay/museum-api.overlay.yaml...
33+
[1] overlay/museum-api.overlay.yaml:5:3 at #/info/description
34+
35+
Property `description` is not expected here.
36+
37+
3 | title: Sample Overlay Configuration
38+
4 | version: 1.0.0
39+
5 | description: ""
40+
6 | extends: openapi.yaml
41+
7 | actions:
42+
43+
Error was generated by the struct rule.
44+
45+
46+
47+
validating overlay/museum-api.overlay.yaml...
48+
[1] overlay/museum-api.overlay.yaml:11:3 at #/actions/1/descript
49+
50+
Property `descript` is not expected here.
51+
52+
Did you mean: description ?
53+
54+
10 | - target: $.paths['/museum-hours']
55+
11 | descript: "not a valid field(misspelled)"
56+
12 | remove: true
57+
58+
Error was generated by the struct rule.
59+
60+
```
61+
62+
## Configure the linting rules
63+
64+
Choose from the ready-made rulesets (`minimal`, `recommended` or `recommended-strict`), or go one better and configure the rules that suit your use case.
65+
There's a full [list of built-in rules for Overlay](../rules/built-in-rules.md#Overlay-rules) to refer to.
66+
67+
Add the rules to `redocly.yaml`, but for Overlay specifications.
68+
The following example shows configuration for the minimal ruleset with additional rules configuration:
69+
70+
```yaml
71+
extends:
72+
- minimal
73+
74+
rules:
75+
info-contact: warn
76+
```
77+
78+
The configuration shown here gives some good entry-level linting using the `minimal` standard, and warns if info contact information is missing.
79+
80+
## Choose output format
81+
82+
Since Redocly CLI is already a fully-featured lint tool, additional features such as a choice of formats are already included.
83+
84+
Get a report in **Markdown format** with the following command:
85+
86+
```bash
87+
redocly lint --format=markdown overlay/museum-api.overlay.yaml
88+
```
89+
90+
Choose your preferred output format from `codeframe`, `stylish`, `json`, `checkstyle`, `codeclimate`, `github-actions`, `markdown`, or `summary`.
91+
The [lint command page](../commands/lint.md) has full details of the command's options.
92+
93+
## Add Overlay linting to GitHub Actions
94+
95+
To make sure that your Overlay description remains valid, add linting to your CI (Continuous Integration) setup.
96+
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.
97+
The following snippet shows an example of configuring a GitHub action for linting:
98+
99+
```yaml
100+
name: Validate museum overlay descriptions
101+
102+
on: [pull_request]
103+
104+
jobs:
105+
build:
106+
runs-on: ubuntu-latest
107+
steps:
108+
- name: Checkout
109+
uses: actions/checkout@v4
110+
- name: Set up node
111+
uses: actions/setup-node@v4
112+
- name: Install Redocly CLI
113+
run: npm install -g @redocly/cli@latest
114+
- name: Run linting
115+
run: redocly lint overlay/*yaml --format=github-actions
116+
```
117+
118+
With this action in place, the intentional errors I added to the Overlay description are shown as annotations on the pull request:
119+
120+
<!-- TODO: Replace with actual image link -->
121+
122+
![Screenshot of annotation flagging "description" as an unexpected value](images/museum-overlay-lint.png)
123+
124+
## Participate in Redocly CLI
125+
126+
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.

‎docs/@v2/rules/built-in-rules.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -149,6 +149,15 @@ The below rules are being migrated to Respect:
149149
- [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`)
150150
- [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`.
151151

152+
## Overlay rules
153+
154+
Rules for the main Overlay specification format.
155+
156+
### Overlay
157+
158+
- [info-contact](./overlay/info-contact.md): Contact section is defined under `info`
159+
- [no-unresolved-refs](./common/no-unresolved-refs.md): Every `$ref` must exist
160+
152161
## Open-RPC rules
153162

154163
Use the rules in this section for Open-RPC specific linting.

0 commit comments

Comments
 (0)