Azure / Azure/azure-rest-api-specs
[Docs cleanup] Archive hand-authored Swagger authoring guides
- Dominant language
- TypeSpec
- Stars
- 3.1k
- Forks
- 5.9k
- Avg merge
- 2d 22h
- Merged PRs (30d)
- 444
Description
**Context:** As part of archiving AutoRest tooling and the move to TypeSpec-only specs (OpenAPI is now
generated via `tsp compile`), the hand-authored Swagger authoring guides no longer describe a supported
workflow. This issue tracks retiring/rewriting them.
**Legend:** 🔴 OBSOLETE (delete/archive) · 🟡 NEEDS-UPDATE (reword)
> ⚠️ The `typespec-autorest` emitter is the current OpenAPI-from-TypeSpec emitter and must NOT be removed.
**Tasks:**
- [ ] 🔴 `documentation/creating-swagger.md` — delete/archive; AutoRest + Swagger 2.0 authoring reference
- [ ] 🔴 `documentation/swagger-extensions.md` — delete/archive; pointer to AutoRest extensions
- [ ] 🔴 `documentation/swagger-bootstrap.json` — delete/archive; hand-authored Swagger 2.0 starter template
- [ ] 🔴 `documentation/openapi-authoring-manual-guidelines.md` — delete, or reduce to a review-only pointer
- [ ] 🔴 `documentation/Getting started with OpenAPI specifications.md` — retire/redirect to TypeSpec getting-started ("we only support Swagger 2.0")
- [ ] 🟡 `documentation/swagger-authoring-descriptions.md` — rewrite for TypeSpec `@doc`/decorators, or retire
- [ ] 🟡 `documentation/swagger-checklist.md` — retarget to TypeSpec/generated-OpenAPI validation; drop any AutoRest validator if they are no longer needed.
Contributor guide
Assessment
This issue has not been assessed yet.