Skip to content

[Docs cleanup] Archive hand-authored Swagger authoring guides #44674

Description

@lirenhe

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.

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