Skip to content

Latest commit

 

History

History
91 lines (71 loc) · 8.69 KB

README.md

File metadata and controls

91 lines (71 loc) · 8.69 KB

Specification documentation

This directory contains documentation specific to the Azure REST API specifications repository.

Getting started

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

Contributor workflow and toolchain

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

Specification structure and lifecycle

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

Pull request checks

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

Validation and rule references

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

Review tooling

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

SDK and release automation implementation

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

Specification testing

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

Legacy OpenAPI samples

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