Getting-started-with-TypeSpec-specifications.md

What is a TypeSpec Specification?

TypeSpec is a versatile language used for describing cloud service APIs and generating various API description languages, client and service code, documentation, and other related assets. It provides highly extensible core language primitives that can describe API structures common among REST, GraphQL, gRPC, and other protocols.

Within the azure-rest-api-specs repository, the TypeSpec specification serves as the source to generate corresponding OpenAPI 2.0 (swagger) API documentation. By utilizing the model and operation patterns found in the standard Azure typespec-core and typespec-resource-manager libraries, TypeSpec offers a much simpler way to express service APIs and ensures compliance with the Azure REST API guidelines for swagger specifications.

Please note TypeSpec specification is REQUIRED for all new ARM services.

TLDR: Key checklist for TypeSpec PR in azure-rest-api-spec repos

General:

• ✅ Do include tspconfig.yaml.
• ✅ Do include examples folder.
• ❌ Do NOT include package.json.
• ❌ Do NOT modify any generated files under resource-manager or data-plane.

ARM:

• ✅ TypeSpec folder name should end with .Management.
• ✅ Starting from tspconfig.yamlARM template. The one thing you may customize is the output json file name for typespec-autorest emitter.

Data-Plane:

• ✅ tspconfig.yaml starting template for Data-plane. For typespec-autorest emitter, you may only customize the output json file name. For other language SDK emitters' settings, you may override values for TypeSpec direct SDK generation.

Detailed information

• Setting up local environment for TypeSpec
• Read up on Folder Structure for TypeSpec
• Setting up a new TypeSpec project
• Setting up and regenerate SDK projects