Azure / Azure/azure-rest-api-specs

[Docs cleanup] Update validation tooling guides to target generated OpenAPI

Open
#44,677 1 comment 0 reactions 1 assignee Claimed by @lmazuel View on GitHub
Docs
Dominant language
TypeSpec
Stars
3.1k
Forks
5.9k
Avg merge
3d 37m
Merged PRs (30d)
446

Description

**Context:** LintDiff/Spectral, OAV, and OAD still run — but on OpenAPI *generated* from TypeSpec. Guidance
that installs/runs AutoRest, or that tells authors to hand-edit Swagger, is out of date. This issue tracks
rewording these guides (and deleting items that no longer used).

**Legend:** 🔴 OBSOLETE (delete/archive) · 🟡 NEEDS-UPDATE (reword)

**Tasks:**

- [ ] 🔴 `documentation/SwaggerValidationTools.md` — obsolete (`npm install -g autorest --azure-validator`); rewrite to LintDiff/OAV/OAD entrypoints
- [ ] 🟡 `documentation/openapi-authoring-automated-guidelines.md` (LintDiff/Spectral rules) — reframe as rules for *generated* OpenAPI; fix AutoRest links
- [ ] 🟡 `documentation/Semantic-and-Model-Violations-Reference.md` (OAV) — keep catalog, change "fix in swagger" → "fix TypeSpec / generated OpenAPI"
- [ ] 🟡 `documentation/ci-fix.md` — split TypeSpec vs generated-OpenAPI checks; drop swagger-authoring assumptions
- [ ] 🟡 `documentation/FAQ.md` — stop presenting Swagger as authoring source; keep validation links
- [ ] 🟡 `documentation/swagger-accuracy-report.md` (RESTler + OAV) — rename swagger wording; process still valid

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.