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:
Create a new TypeSpec Azure project
-
Run
tsp init
command with Azure template URLhttps://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 intsp-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
Getting Started for Azure Data Plane Services
- Documentation
- Samples
- Petstore Sample using Low-level Http APIs
- Petstore Sample using High-level Resource APis
- You can also browse the Samples package
- Video Walkthroughs
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
- For bugs, please include:
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: