Update governance documentation with custom ruleset configuration - #427
Update governance documentation with custom ruleset configuration#427Thenujan-Nagaratnam wants to merge 2 commits into
Conversation
… debugging instructions
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughThe VS Code API Designer guide updates its metadata date and adds instructions for configuring, customizing, and troubleshooting Spectral rulesets through VS Code settings. ChangesSpectral Ruleset Documentation
Estimated code review effort: 1 (Trivial) | ~5 minutes 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@en/docs/tools/vscode-api-design/govern-apis.md`:
- Around line 82-84: Update the “To configure it from the Settings UI”
instructions and the referenced lines to use <kbd>...</kbd> for all keyboard
shortcuts, bold the specified UI labels and Settings JSON commands, and define
UI on first use as “user interface (UI)”.
- Line 115: Update the troubleshooting text around the custom ruleset behavior
and the related instructions at line 123 by splitting sentences so each stays
within the 26-word limit. Format the HTTP status values 401 and 403 as code, and
define YAML at its first occurrence.
- Line 105: Format the repository path in the link text as inline code by
wrapping it in backticks, while preserving the existing repository URL and
surrounding documentation.
- Around line 80-86: Update the rulesetFolder configuration instructions to
state that it is supported only at window/workspace scope, removing the claim
that it can be configured in global User settings. Revise the surrounding
custom-ruleset failure description to clarify that load or parse failures fall
back to the bundled ruleset for the affected report, not the entire analysis.
- Line 87: Rewrite the step in the VS Code setup instructions as two sentences:
first instruct entering the GitHub folder URL or absolute local directory path,
then conditionally instruct reloading only if VS Code prompts. Use the prompt’s
exact UI label, changing “reload the folder” to “reload window” if that is what
VS Code displays.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 19e3b7ce-edd4-4f92-b764-fa8bf28ddd0d
📒 Files selected for processing (1)
en/docs/tools/vscode-api-design/govern-apis.md
| By default, API Designer runs the three bundled Spectral rulesets listed above. You can point it at your own ruleset folder instead, either to override individual rules or to replace a report's rules entirely. | ||
|
|
||
| **To configure it from the Settings UI:** | ||
|
|
||
| 1. Open Settings: `Ctrl+,` / `Cmd+,`, or open the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`) and run **Preferences: Open Settings (UI)**. | ||
| 2. Search for `apiDesigner.spectral.rulesetFolder`. | ||
| 3. Choose the **User** tab to apply it across all of VS Code, or the **Workspace** tab to scope it to the current project only. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
tmp_dir="$(mktemp -d)"
trap 'rm -rf "$tmp_dir"' EXIT
git clone --depth 1 https://github.com/wso2/vscode-extensions.git \
"$tmp_dir/vscode-extensions"
rg -n -C 8 \
'apiDesigner\.spectral\.rulesetFolder|rulesetFolder|workspace|GitHub|local|reload' \
"$tmp_dir/vscode-extensions/workspaces/api-designer/api-designer-extension"Repository: wso2/docs-api-platform
Length of output: 50379
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
tmp_dir="$(mktemp -d)"
trap 'rm -rf "$tmp_dir"' EXIT
git clone --depth 1 https://github.com/wso2/vscode-extensions.git \
"$tmp_dir/vscode-extensions"
# Inspect configuration schema and focused implementation around the ruleset settings.
python3 - <<'PY'
import json, pathlib, re
root = pathlib.Path('${tmp_dir}/vscode-extensions/workspaces/api-designer/api-designer-extension')
files = {}
for path in root.rglob('*'):
if path.is_file() and (
path.name == 'package.json' or 'validation-utils.ts' in str(path) or 'github-utils.ts' in str(path)
):
files[str(path)] = path.read_text(encoding='utf-8', errors='replace')
# Extract the full package.json contribution with settings.
pk = files.get(str(path(root, 'package.json')), '')
m = re.search(r'"contributes"[^}]+}', pk, flags=re.S)
if m:
print('--- package contributes snippet ---')
print(m.group(0)[:4000])
# Print focused validation-utils context for ruleset loading.
for path, text in files.items():
if 'validation-utils.ts' in str(path):
print(f'--- {path} ---')
lines = text.splitlines()
for i, line in enumerate(lines, 1):
if any(s in line for s in [
'apiDesigner.spectral.rulesetFolder',
'configuration',
'getRulesetFromConfiguration',
'isUrl',
'resolveGitHubRawUrl',
'fetchSpectralRuleset',
'loadSpectralRuleset',
]):
start = max(1, i-12)
end = min(len(lines), i+20)
print("--- lines", start, "-", end, "---")
for n in range(start, end+1):
print(f"{n}: {lines[n-1]}")
# Print focused github-utils definitions and tests if present.
for path, text in files.items():
if 'github-utils.ts' in str(path):
print(f'--- {path} ---')
for i, line in enumerate(text.splitlines(), 1):
if any(s in line for s in ['export function resolveGitHubRawUrl', 'resolveGitHubRawUrl', 'function resolveGitHubRawUrl']):
start = max(1, i-8)
end = min(len(text.splitlines()), i+25)
print("--- lines", start, "-", end, "---")
for n in range(start, end+1):
print(f"{n}: {text.splitlines()[n-1]}")
# Inspect tests mentioning rulesetFolder, tree, raw, vscode workspace config.
for path, text in files.items():
if ('test' in str(path) or 'tests' in str(path)) and (path.suffix in ['.ts', '.js', '.json']):
if any(s in text for s in ['rulesetFolder', 'apiDesigner.spectral.rulesetFolder', 'GitHub', 'workspace', 'User']):
print(f'--- {path} ---')
for i, line in enumerate(text.splitlines(), 1):
if any(s in line for s in ['rulesetFolder', 'apiDesigner.spectral.rulesetFolder', 'GitHub', 'workspace', 'User']):
start = max(1, i-5)
end = min(len(text.splitlines()), i+8)
for n in range(start, end+1):
print(f"{n}: {text.splitlines()[n-1]}")
PYRepository: wso2/docs-api-platform
Length of output: 328
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
tmp_dir="$(mktemp -d)"
trap 'rm -rf "$tmp_dir"' EXIT
git clone --depth 1 https://github.com/wso2/vscode-extensions.git \
"$tmp_dir/vscode-extensions"
# Locate the exact implementation references for the settings and ruleset loading path.
rg -n 'apiDesigner\.spectral\.rulesetFolder|rulesetFolder|rulesetContent|rulefile|getConfiguration\(|vscode\.workspace\.getConfiguration|resolveGitHubRawUrl|tree/|raw' \
"$tmp_dir/vscode-extensions/workspaces/api-designer/api-designer-extension" \
--glob '!**/node_modules/**' --glob '!**/dist/**' \
--glob 'package.json' --glob '*.ts' | head -n 200Repository: wso2/docs-api-platform
Length of output: 33190
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
tmp_dir="$(mktemp -d)"
trap 'rm -rf "$tmp_dir"' EXIT
git clone --depth 1 https://github.com/wso2/vscode-extensions.git \
"$tmp_dir/vscode-extensions"
base="$tmp_dir/vscode-extensions/workspaces/api-designer/api-designer-extension"
echo '--- settings schema ---'
sed -n '220,238p' "$base/package.json" | cat -n
echo '--- rulesetAutomation lines 1-130 ---'
sed -n '1,130p' "$base/src/spectral/rulesetAutomation.ts" | cat -n
echo '--- rulesetAutomation lines 230-315 ---'
sed -n '230,315p' "$base/src/spectral/rulesetAutomation.ts" | cat -n
echo '--- src/utils/github-utils.ts line 200-435 ---'
sed -n '200,435p' "$base/src/utils/github-utils.ts" | cat -n
echo '--- src/rpc-managers/api-designer-visualizer/managers/governance-manager.ts lines 580-700 ---'
sed -n '580,700p' "$base/src/rpc-managers/api-designer-visualizer/managers/governance-manager.ts" | cat -n
echo '--- focused rule: does config resolve a file from a GitHub tree/folder URL? ---'
python3 - <<'PY'
from pathlib import Path
import re, textwrap
base = Path('${tmp_dir}/vscode-extensions/workspaces/api-designer/api-designer-extension')
for rel in [
Path('src/spectral/rulesetAutomation.ts'),
Path('src/rpc-managers/api-designer-visualizer/managers/governance-manager.ts'),
]:
text = (base / rel).read_text()
fn_name = (rel / 'src' / 'rpc-managers').relative_to(
Path('${tmp_dir}/vscode-extensions/workspaces/api-designer/api-designer-extension/src'))\
if False else None
print(f'--- {rel} ---')
for i,line in enumerate(text.splitlines(),1):
if 'apiDesigner.spectral.rulesetFolder' in line or 'readDiscoveredRulesets' in line or 'rulesetContentPath' in line or 'resolveGitHubRawUrl' in line:
start=max(1,i-5); end=min(len(text.splitlines()), i+15)
for n in range(start,end+1):
print(f'{n}: {text.splitlines()[n-1]}')
PYRepository: wso2/docs-api-platform
Length of output: 30208
Correct the ruleset scope and failure behavior.
apiDesigner.spectral.rulesetFolder is limited to window scope and does not accept global User settings. Also, a custom ruleset load/parse failure falls back to the bundled default for that report instead of the whole analysis; remove the fallback-to-default analysis wording or rephrase it per report.
🧰 Tools
🪛 LanguageTool
[style] ~80-~80: Since ownership is already implied, this phrasing may be redundant.
Context: ...esets listed above. You can point it at your own ruleset folder instead, either to overr...
(PRP_OWN)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@en/docs/tools/vscode-api-design/govern-apis.md` around lines 80 - 86, Update
the rulesetFolder configuration instructions to state that it is supported only
at window/workspace scope, removing the claim that it can be configured in
global User settings. Revise the surrounding custom-ruleset failure description
to clarify that load or parse failures fall back to the bundled ruleset for the
affected report, not the entire analysis.
| **To configure it from the Settings UI:** | ||
|
|
||
| 1. Open Settings: `Ctrl+,` / `Cmd+,`, or open the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`) and run **Preferences: Open Settings (UI)**. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Use the required Markdown markup for UI labels and keyboard input.
Use <kbd> for keyboard shortcuts instead of backticks. Bold labels such as Settings, Command Palette, User, Workspace, and the Settings JSON commands. Define UI as “user interface (UI)” at first use.
Also applies to: 86-86, 91-92, 101-101, 121-121
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@en/docs/tools/vscode-api-design/govern-apis.md` around lines 82 - 84, Update
the “To configure it from the Settings UI” instructions and the referenced lines
to use <kbd>...</kbd> for all keyboard shortcuts, bold the specified UI labels
and Settings JSON commands, and define UI on first use as “user interface (UI)”.
Sources: Coding guidelines, Path instructions
| 1. Open Settings: `Ctrl+,` / `Cmd+,`, or open the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`) and run **Preferences: Open Settings (UI)**. | ||
| 2. Search for `apiDesigner.spectral.rulesetFolder`. | ||
| 3. Choose the **User** tab to apply it across all of VS Code, or the **Workspace** tab to scope it to the current project only. | ||
| 4. Enter a GitHub folder URL (for example `https://github.com/<org>/<repo>/tree/main/<path>`) or an absolute local directory path, then reload the folder if prompted. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== candidate file =="
fd -a 'govern-apis\.md$' . || true
echo "== file excerpt =="
if [ -f en/docs/tools/vscode-api-design/govern-apis.md ]; then
nl -ba en/docs/tools/vscode-api-design/govern-apis.md | sed -n '70,95p'
fi
echo "== repo markdown files mentioning 'reload the folder' =="
rg -n "reload the folder|reload folder|reload window|reload" -g '*.md' en/docs/tools/vscode-api-design || true
echo "== locate vscode/api designer sources =="
git ls-files | rg -i '(^|/)(vscode|api[ _-]?designer|design|extension|package)\.(json|ts|js)$|vscode-api' || trueRepository: wso2/docs-api-platform
Length of output: 306
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Inspect likely extension sources and package/commands for the VS Code reload behavior if present.
python3 - <<'PY'
import subprocess, re
files=subprocess.check_output(['git','ls-files'], text=True).splitlines()
targets={}
for f in files:
if f.lower().startswith('vscode') or re.search(r'\b(vscode|api.?design|designer|extension)\b', f, re.I):
targets[f]=1
print("\n".join(sorted(targets)[:200]))
# Search command text across all files without executing repo code.
matches=[]
for f in files[:5000]:
try:
data=open(f, encoding='utf-8', errors='replace').read()
except Exception:
continue
if re.search(r'reload|folder|GitHub folder|tree/main|extension\.reload|commands\.', data, re.I):
for i,line in enumerate(data.splitlines(),1):
if re.search(r'reload|folder|GitHub folder|tree/main|extension\.reload|commands\.', line, re.I):
matches.append((f,i,line.strip()))
for m in matches[:300]:
print(f"{m[0]}:{m[1]}: {m[2]}")
PYRepository: wso2/docs-api-platform
Length of output: 50379
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== candidate file =="
fd -a 'govern-apis\.md$' . || true
echo "== file excerpt =="
if [ -f en/docs/tools/vscode-api-design/govern-apis.md ]; then
nl -ba en/docs/tools/vscode-api-design/govern-apis.md | sed -n '70,95p'
fi
echo "== repo markdown files mentioning relevant reload wording =="
rg -n "reload the folder|reload folder|reload window|VS Code prompts|prompts you|prompt" -g '*.md' en/docs/tools/vscode-api-design en/docs 2>/dev/null || true
echo "== VS Code/designer/package references =="
python3 - <<'PY'
import subprocess, re
files=subprocess.check_output(['git','ls-files'], text=True).splitlines()
for f in files:
if re.search(r'(^|/)(.*vscode.*|.*vscode.*|.*api.?design.*|.*designer.*|package\.json|manifest|README)', f, re.I):
print(f)
PYRepository: wso2/docs-api-platform
Length of output: 306
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== candidate file =="
fd -a 'govern-apis\.md$' . || true
echo "== file excerpt =="
if [ -f en/docs/tools/vscode-api-design/govern-apis.md ]; then
nl -ba en/docs/tools/vscode-api-design/govern-apis.md | sed -n '70,95p'
fi
echo "== VS Code/designer package references and key commands =="
python3 - <<'PY'
import subprocess, re
files=subprocess.check_output(['git','ls-files'], text=True).splitlines()
for f in files:
if re.search(r'(^|/)(.*vscode.*|.*api.?design.*|.*designer.*|package\.json|README)', f, re.I):
print(f)
PYRepository: wso2/docs-api-platform
Length of output: 306
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== target file and changed line =="
if [ -f en/docs/tools/vscode-api-design/govern-apis.md ]; then
nl -ba en/docs/tools/vscode-api-design/govern-apis.md | sed -n '80,90p'
else
echo "target file missing"
fi
echo "== code/package references for reload wording =="
python3 - <<'PY'
import subprocess, re
files=subprocess.check_output(['git','ls-files'], text=True).splitlines()
counts={}
for f in files:
try:
data=open(f, encoding='utf-8', errors='replace').read()
except Exception:
continue
if re.search(r'reload|extension\.reload|commandPrompt|folder|GitHub folder|tree/main', data, re.I):
matches=[]
for i,line in enumerate(data.splitlines(),1):
if re.search(r'reload|GitHub folder|tree/main|commandPrompt|extension\.reload', line, re.I):
matches.append((i,line.strip()))
counts[f]=matches
for f,matches in sorted(counts.items()):
print(f"## {f}")
for i,line in matches[:20]:
print(f"{i}: {line}")
PYRepository: wso2/docs-api-platform
Length of output: 235
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== target file and changed line =="
nl -ba en/docs/tools/vscode-api-design/govern-apis.md | sed -n '80,90p'
echo "== code/package references for reload wording =="
python3 - <<'PY'
import subprocess, re
files=subprocess.check_output(['git','ls-files'], text=True).splitlines()
counts={}
for f in files:
try:
data=open(f, encoding='utf-8', errors='replace').read()
except Exception:
continue
if re.search(r'reload|extension\.reload|commandPrompt|folder|GitHub folder|tree/main', data, re.I):
matches=[]
for i,line in enumerate(data.splitlines(),1):
if re.search(r'reload|GitHub folder|tree/main|commandPrompt|extension\.reload', line, re.I):
matches.append((i,line.strip()))
counts[f]=matches
for f,matches in sorted(counts.items()):
print(f"## {f}")
for i,line in matches[:20]:
print(f"{i}: {line}")
PYRepository: wso2/docs-api-platform
Length of output: 235
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== target excerpt =="
awk 'NR>=80 && NR<=90 {printf "%d\t%s\n", NR, $0}' en/docs/tools/vscode-api-design/govern-apis.md
echo "== reload/folder mentions in target doc =="
awk 'NR>=1 && NR<=160' en/docs/tools/vscode-api-design/govern-apis.md | grep -i --regexp='reload|folder|prompt|window|reload window' || true
echo "== focused repo text search =="
python3 - <<'PY'
import subprocess, re
files = subprocess.check_output(['git','ls-files'], text=True).splitlines()
seen = set()
needs = {'vscode', 'vs_code', 'vscode-api', 'extension', 'package.json', 'designer'}
for f in files:
if not any(s in f.lower() for s in needs):
continue
if f.endswith(('.png','.jpg','.jpeg','.gif','.svg')):
continue
try:
data = open(f, encoding='utf-8', errors='replace').read()
except Exception:
continue
if re.search(r'reload|folder|prompt|window|GitHub folder|tree/main', data, re.I):
hits = []
for i,line in enumerate(data.splitlines(), 1):
if re.search(r'reload|folder|prompt|window|GitHub folder|tree/main', line, re.I):
hits.append((i,line.strip()))
if hits:
if f in seen:
continue
seen.add(f)
print(f"## {f}")
for i,line in hits[:25]:
print(f"{i}: {line}")
PYRepository: wso2/docs-api-platform
Length of output: 3686
🌐 Web query:
VS Code preferences: Open Settings (UI) reload required after changing extension settings prompt folder
💡 Result:
In Visual Studio Code, a "reload required" prompt after changing extension settings indicates that the modified setting cannot be applied dynamically by the extension while it is running [1][2]. Because the Visual Studio Code architecture does not provide a native mechanism for forcing an individual extension to reload its configuration or state, some extensions require a full window reload to initialize with the new values [1][2]. When you encounter this prompt, you can apply the changes by reloading the window using one of the following methods: 1. Command Palette: Press Ctrl+Shift+P (or Cmd+Shift+P on macOS), type "Developer: Reload Window", and press Enter [3]. 2. Restarting: If a specific "Restart" action or button is provided by the UI in the notification or the Extensions view, you can use it to trigger the necessary reload [3][4]. While some extensions are designed to listen for configuration changes using the onDidChangeConfiguration API—allowing them to update dynamically without a reload—this depends entirely on the extension author's implementation [1]. If an extension does not support this, a reload is the standard requirement to ensure the new settings take effect [2]. Note that recent improvements to Visual Studio Code have introduced more specific messaging for these scenarios [5], and some newer features (often appearing first in Insider builds) aim to streamline the process of restarting extensions or the window when updates or changes are required [4][6]. If you see this prompt persistently, it is typically because the extension specifically marked those settings as requiring a restart [2].
Citations:
- 1: Ability to reload single extension instead reloading entire window/all extensions. microsoft/vscode-discussions#1531
- 2: https://learn.microsoft.com/en-us/microsoft-edge/visual-studio-code/microsoft-edge-devtools-extension/change-extension-settings
- 3: https://stackoverflow.com/questions/42002852/how-to-restart-vscode-after-editing-extensions-config
- 4: Add support for restart required extensions in the extensions view microsoft/vscode#293861
- 5: Improve messages about restart / reload after extension update (fix #297278) microsoft/vscode#307353
- 6: Just restart EH automatically on extension update? microsoft/vscode#214424
Put the reload condition before the action.
Rewrite line 87 as two steps so the action depends on the prompt: “Enter a GitHub folder URL … or an absolute local directory path. If VS Code prompts you, reload the folder.” Confirm whether the prompt says reload window instead of reload folder; use that UI label if it does.
Proposed wording
-Enter a GitHub folder URL (for example `https://github.com/<org>/<repo>/tree/main/<path>`) or an absolute local directory path, then reload the folder if prompted.
+Enter a GitHub folder URL (for example `https://github.com/<org>/<repo>/tree/main/<path>`) or an absolute local directory path. If VS Code prompts you, reload the folder.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| 4. Enter a GitHub folder URL (for example `https://github.com/<org>/<repo>/tree/main/<path>`) or an absolute local directory path, then reload the folder if prompted. | |
| 4. Enter a GitHub folder URL (for example `https://github.com/<org>/<repo>/tree/main/<path>`) or an absolute local directory path. If VS Code prompts you, reload the folder. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@en/docs/tools/vscode-api-design/govern-apis.md` at line 87, Rewrite the step
in the VS Code setup instructions as two sentences: first instruct entering the
GitHub folder URL or absolute local directory path, then conditionally instruct
reloading only if VS Code prompts. Use the prompt’s exact UI label, changing
“reload the folder” to “reload window” if that is what VS Code displays.
Sources: Coding guidelines, Path instructions
|
|
||
| **Start from the bundled rulesets.** The simplest way to build a custom ruleset is to copy WSO2's bundled ones and customize them: | ||
|
|
||
| [wso2/vscode-extensions → workspaces/api-designer/api-designer-extension/spectral-rulesets](https://github.com/wso2/vscode-extensions/tree/main/workspaces/api-designer/api-designer-extension/spectral-rulesets) |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Format the repository path as code.
The link text contains a repository path. Use descriptive link text, or wrap the path in backticks.
Proposed wording
-[wso2/vscode-extensions → workspaces/api-designer/api-designer-extension/spectral-rulesets](https://github.com/wso2/vscode-extensions/tree/main/workspaces/api-designer/api-designer-extension/spectral-rulesets)
+[WSO2 bundled Spectral rulesets](https://github.com/wso2/vscode-extensions/tree/main/workspaces/api-designer/api-designer-extension/spectral-rulesets)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| [wso2/vscode-extensions → workspaces/api-designer/api-designer-extension/spectral-rulesets](https://github.com/wso2/vscode-extensions/tree/main/workspaces/api-designer/api-designer-extension/spectral-rulesets) | |
| [WSO2 bundled Spectral rulesets](https://github.com/wso2/vscode-extensions/tree/main/workspaces/api-designer/api-designer-extension/spectral-rulesets) |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@en/docs/tools/vscode-api-design/govern-apis.md` at line 105, Format the
repository path in the link text as inline code by wrapping it in backticks,
while preserving the existing repository URL and surrounding documentation.
Sources: Coding guidelines, Path instructions
| | OWASP API Security Top 10 | `owasp_top_10.yaml` | | ||
| | WSO2 REST API Design Guidelines | `wso2_rest_api_design_guidelines.yaml` | | ||
|
|
||
| If a custom ruleset fails to load or parse, API Designer shows a warning and falls back to the bundled default for that report, so analysis is never blocked. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Split the troubleshooting sentences and define technical terms.
Line 115 exceeds the 26-word limit. Line 123 also exceeds it. Split both instructions into short sentences. Format 401 and 403 as code. Define YAML at first use.
Also applies to: 123-123
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@en/docs/tools/vscode-api-design/govern-apis.md` at line 115, Update the
troubleshooting text around the custom ruleset behavior and the related
instructions at line 123 by splitting sentences so each stays within the 26-word
limit. Format the HTTP status values 401 and 403 as code, and define YAML at its
first occurrence.
Sources: Coding guidelines, Path instructions
1 participant
This pull request updates the API governance documentation for API Designer with instructions on using custom Spectral rulesets. The main addition is a new section explaining how to configure API Designer to use user-provided rulesets, including step-by-step guides for both the Settings UI and
settings.json, as well as troubleshooting tips.Custom ruleset support and documentation:
settings.jsonediting, with guidance on scoping settings to user or workspace level.