typespec-getting-started

What is TypeSpec?

TypeSpec (Compact API Definition Language) is a typescript-like language for defining APIs. TypeSpec is designed for code reuse, and for Azure services, there are Azure service extensions for TypeSpec that provide high level building blocks you should use to build your service. These libraries also contain rules that encourage following established patterns for Azure APIs. Using these building blocks and guard rails, your service API will be easier to build, will have an easier time passing API reviews, will be consistent with other Azure services, and will produce good API documentation, good SDKs, and good CLIs. TypeSpec can emit the following artifacts for your service:

• OpenAPI3 specs
• OpenAPI2 specs, suitable for check-in in to the azure-rest-api-specs repo

For more information on the TypeSpec language and core libraries, see Getting started with TypeSpec

Setting up TypeSpec and compile first project

Install TypeSpec

There are two simple options for getting TypeSpec up and running in your environment:

• Install directly from npm

• Use the TypeSpec docker images

Create a new TypeSpec Azure project

• Run tsp init command with Azure template URL https://aka.ms/typespec/azure-init to create a new TypeSpec Azure project for ARM or Data-plane service APIs. This will initialize an empty TypeSpec project with correct npm package references and emitter settings for Azure services.

• Run tsp compile in the project folder will compile the TypeSpec project and emit output in tsp-output folder.

Once TypeSpec project has been create, the TypeSpec language tutorial provides a good overview of the basics of the language.

Getting Started for Azure Management Plane Services

Use the resources in this section for creating Azure ARM rest API specs. For ProviderHub User RP specs and service implementation, please follow the steps in the next section.

• Documentation
  • TypeSpec Azure ARM library

Getting Started for Azure Data Plane Services

• Documentation
  • Getting started with TypeSpec for REST APIs
  • TypeSpec language tutorial
  • TypeSpec Swagger Cheat Sheet
• Samples
  • Petstore Sample using Low-level Http APIs
  • Petstore Sample using High-level Resource APis
  • You can also browse the Samples package
• Video Walkthroughs
  • Getting Started with TypeSpec

How to Get Help

• Ask questions in the TypeSpec Discussions Channel
• File issues in the typespec-azure github repo
  • For bugs, please include:
    • A high-level description of the bug
    • Expected and Actual Results
    • Repro steps, including any TypeSpec code that you used
    • Any error messages you saw, including stack traces. For issues with VS or VS Code tooling see Troubleshooting VSCode Tooling and Filing Issues

Troubleshooting VSCode Tooling and Filing Issues

If you run into a problem with the TypeSpec-specific tooling in VS Code, please try to capture the issue, and include any log information. If IntelliSense, syntax highlighting or other language features don't appear to be working:

• Ensure that 'TypeSpec' is the selected language format for your document (this should happen automatically if your file uses the .tsp suffix)
• Choose Output from the View menu to see the output of the language server (View -> Output)
• Capture any output, including stack traces, and include in your github issue.
• Restart VS Code to restart the language server

More Information About TypeSpec

Some additional sources:

• Recordings
  • TypeSpec lunch-and-learn for ARM in Stream Channel
  • TypeSpec lunch-and-learn for Azure SDK