Skip to content

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

Description

@lirenhe

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions