Azure / Azure/azure-rest-api-specs

[Docs cleanup] Archive hand-authored Swagger authoring guides

Open
#44,674 1 comment 0 reactions 1 assignee Claimed by @haolingdong-msft View on GitHub
Docs
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

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.