Azure / Azure/azure-rest-api-specs
[Docs cleanup] Update validation tooling guides to target generated OpenAPI
- 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
Assessment
This issue has not been assessed yet.