documentation

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

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
Uniform versioning	Repository requirements for versioning a service, its specifications, documentation, and SDKs together.	Specification authors and reviewers	TypeSpec and 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