This directory contains documentation specific to the Azure REST API specifications repository.
| Document | Purpose | Audience | Applies to |
|---|---|---|---|
| Getting started with TypeSpec specifications | Repository checklist and starting points for TypeSpec specification projects. | Specification authors | TypeSpec |
| Getting started with OpenAPI specifications | Starting points for maintaining hand-authored OpenAPI specifications. | Specification authors maintaining existing OpenAPI | OpenAPI |
| Document | Purpose | Audience | Applies to |
|---|---|---|---|
| Toolchain setup | Node.js and pnpm prerequisites, installation, and toolchain updates. | Contributors | TypeSpec and OpenAPI |
| Dependencies | Workspace package management, dependency ownership, and shared versions. | Contributors and tooling maintainers | Repository tooling |
| TypeSpec development process | End-to-end setup, authoring, pull request, and SDK development workflow. | Specification authors | TypeSpec |
| API specification review FAQ | Where to get help with review queues, checks, and documentation publishing. | Pull request authors | TypeSpec and OpenAPI |
| Spec model | Running the repository's specification model locally and diagnosing errors. | Contributors and tooling maintainers | TypeSpec and OpenAPI |
| Document | Purpose | Audience | Applies to |
|---|---|---|---|
| Folder structure versions | Overview of the current and legacy specification layouts. | Specification authors | TypeSpec and OpenAPI |
| Specification folder structure guide | Detailed directory layout, naming, and migration requirements. | Specification authors | TypeSpec and OpenAPI |
| Specification glossary | Definitions of services, organizations, resource types, and provider namespaces. | Specification authors and reviewers | TypeSpec and OpenAPI |
| Azure service versioning guide | Service boundaries, versioning, and service-specific SDK packages. | Service teams | TypeSpec and OpenAPI |
| Uniform versioning | Requirements for versioning a service, its specifications, documentation, and SDKs together. | Specification authors and reviewers | TypeSpec and OpenAPI |
| Common types | Usage guidance for shared resource-management types. | Management-plane specification authors | TypeSpec and OpenAPI |
| Deprecating preview APIs | Policies and steps for removing retired preview API versions. | Service teams | TypeSpec and OpenAPI |
| Resolving folder migration conflicts | Updating an in-flight pull request after a folder migration. | Pull request authors | TypeSpec and OpenAPI |
Start with the CI fix guide to identify a failing check, then use its detailed reference below.
| Document | Purpose | Audience | Applies to |
|---|---|---|---|
| API documentation preview | Documentation onboarding, preview pipeline behavior, and troubleshooting. | Specification authors | TypeSpec and OpenAPI |
| ARM auto sign-off | Queries and implementation references for automatic ARM sign-off. | Reviewers and tooling maintainers | Management-plane specifications |
| SDK breaking changes | Suppressing and reviewing SDK breaking changes. | Specification authors and SDK reviewers | TypeSpec and OpenAPI |
| SDK validation | Re-running checks, downloading artifacts, and diagnosing SDK generation errors. | Pull request authors | TypeSpec and OpenAPI |
| Summarize impact | Change classification and suppression-review troubleshooting. | Reviewers and tooling maintainers | TypeSpec and OpenAPI |
| Swagger Avocado | Running specification structure checks and handling known errors. | Pull request authors | TypeSpec and OpenAPI |
| Swagger breaking change troubleshooting | Diagnosing AutoRest exceptions in breaking-change checks. | Pull request authors | OpenAPI |
| Swagger LintDiff | Scoped suppressions and TypeSpec-generated OpenAPI troubleshooting. | Specification authors | TypeSpec and OpenAPI |
| TypeSpec requirement | TypeSpec adoption checks, suppressions, and renamed specifications. | Specification authors | TypeSpec and OpenAPI |
| TypeSpec validation | Local validation, rule behavior, and suppression configuration. | Specification authors | TypeSpec |
| Uniform versioning violation guide | Resolving version mixing and its SDK release implications. | Service teams | TypeSpec and OpenAPI |
| Document | Purpose | Audience | Applies to |
|---|---|---|---|
| CI fix guide | Troubleshooting entry point for pull request validation checks. | Pull request authors | TypeSpec and OpenAPI |
| OpenAPI authoring automated guidelines | Reference for automated OpenAPI validation rules and their TypeSpec mappings. | Specification authors and reviewers | TypeSpec and OpenAPI |
| OpenAPI authoring manual guidelines | Reference for OpenAPI authoring rules that require manual verification. | Specification authors and reviewers | OpenAPI |
| Semantic and model violations reference | Reference for OAV semantic and model validation errors. | OpenAPI authors | OpenAPI |
| Breaking change and OAD rules mapping | Mapping between OAD rule identifiers and breaking change categories. | Specification authors and reviewers | OpenAPI |
| x-ms-examples | Repository reference for operation request and response examples in OpenAPI. | OpenAPI authors | OpenAPI |
| Document | Purpose | Audience | Applies to |
|---|---|---|---|
| ARM API Reviewer agent | User and maintainer documentation for the repository's ARM API review agent. | Specification authors, reviewers, and agent maintainers | TypeSpec and OpenAPI |
| Backlog triage | Automatic oldest-first issue investigation, cleanup criteria, and maintainer controls. | Issue reporters and repository maintainers | Repository issues |
| Document | Purpose | Audience | Applies to |
|---|---|---|---|
| Official SDK release guide | Process for requesting and releasing an official Azure SDK. | Service teams | TypeSpec and OpenAPI |
| Release plan auto-generation | Implementation details for automatic release plan discovery and creation. | Tooling maintainers | TypeSpec |
| SDK automation customization | Configuration and protocol reference for SDK automation. | Tooling maintainers | TypeSpec and OpenAPI |
| Document set | Purpose | Audience | Applies to |
|---|---|---|---|
| API Scenario | Authoring and reference documentation for API Scenario tests. | Service teams and test authors | OpenAPI-based scenarios |
| RESTler | Setup and recording guidance for RESTler API testing. | Service teams and test authors | OpenAPI |
| Document set | Purpose | Audience | Applies to |
|---|---|---|---|
| Resource Manager sample files | Legacy sample OpenAPI specifications and AutoRest configuration files. | Authors maintaining existing OpenAPI | OpenAPI |
| Data-plane sample files | Legacy single-client and multi-client OpenAPI samples. | Authors maintaining existing OpenAPI | OpenAPI |