Repository files navigation

Official Docs |Try TypeSpec Online |Getting Started |Language Overview

TypeSpec is a language for defining cloud service APIs and shapes. TypeSpec is a highly extensible language with primitives that can describe API shapes common among REST, OpenAPI, gRPC, and other protocols.

TypeSpec is excellent for generating many different API description formats, client and service code, documentation, and other assets while keeping your TypeSpec definition as a single source of truth.

Using TypeSpec, you can create reusable patterns for all aspects of an API and package those reusable patterns into libraries. These patterns establish "guardrails" for API designers and make it easier to follow best practices than to deviate from them. TypeSpec also has a rich linter framework with the ability to flag anti-patterns as well as an emitter framework that lets you control the output to ensure it follows the patterns you want.

TypeSpec is a Microsoft-built, community-supported project. Your ideas, feedbacks, and code make all the difference and we deeply appreciate the support from the community.

npm install -g @typespec/compiler

TheTypeSpec VS Code extension can be installed from the VS Codemarketplace or directly on the command line:

tsp code install

TheTypeSpec VS Extension can be installed from theVS Marketplace or directly on the command line:

tsp vs install

This example uses the@typespec/http,@typespec/rest, and@typespec/openapi3 libraries to define a basic REST service and generate an OpenAPI 3.0 document from it.

Run the following command and select "Generic REST API":

tsp init

Hit enter a few times to confirm the defaults.

Copy the contents below into yourmain.tsp:

import"@typespec/http";import"@typespec/rest";import"@typespec/openapi3";usingHttp;usingRest;/** This is a pet store service.*/@service(#{title:"Pet Store Service" })@server("https://example.com","The service endpoint")namespacePetStore;@route("/pets")interfacePets {list():Pet[];}modelPet {@minLength(100)name:string;@minValue(0)@maxValue(100)age:int32;kind:"dog" |"cat" |"fish";}

Install the dependencies of main.tsp:

tsp install

Compile it to OpenAPI 3.0:

tsp compile main.tsp --emit @typespec/openapi3

You can find the emitted OpenAPI output in./tsp-output/openapi.json.

On every commit to the main branch, packages with changes are automatically published to npm with the@next tag.Thepackages section shows which version corresponds to thenext tag for each package.

To use anightly version of the packages, go over each one of the packages in thepackage.json file and update it to either the latest published@next version or@latest, whichever is the newest. You can also use the taglatest ornext instead of an explicit version.

After updating the package.json file you can runnpm update --force. Force is required as there might be some incompatible version requirement.

Example

// Stable setup"dependencies":{"@typespec/compiler":"~0.30.0","@typespec/http":"~0.14.0","@typespec/rest":"~0.14.0","@typespec/openapi":"~0.9.0",}// Consume next version// In this example: compiler and openapi have changes but rest library has none"dependencies":{"@typespec/compiler":"~0.31.0-dev.5","@typespec/http":"~0.14.0","@typespec/rest":"~0.14.0",// No changes to@typespec/rest library so need to stay the latest."@typespec/openapi":"~0.10.0-dev.2",}

Name	Changelog	Latest	Next
Core functionality
@typespec/compiler	Changelog
TypeSpec Libraries
@typespec/http	Changelog
@typespec/rest	Changelog
@typespec/openapi	Changelog
@typespec/openapi3	Changelog
@typespec/versioning	Changelog
TypeSpec Tools
@typespec/prettier-plugin-typespec	Changelog
typespec-vs	Changelog
typespec-vscode	Changelog
tmlanguage-generator	Changelog

@next version of the package are the latest versions available on themain branch.