Перейти к файлу
Timothee Guerin bb7d035c56
Add blog back to astro (#4797)
2024-10-21 18:16:29 +00:00
.chronus Fix float32/float64 docs (#4779) 2024-10-17 20:34:26 +00:00
.devcontainer Add dev container configuration for repo (#3440) 2024-05-24 00:20:36 +00:00
.github update ownership for IDE related code (#4755) 2024-10-16 15:19:15 +00:00
.vscode Migrate website to astro [Step 1] (#4587) 2024-10-11 01:38:03 +00:00
blog/2024-04-25-introducing Add blog back to astro (#4797) 2024-10-21 18:16:29 +00:00
docker Add dev container configuration for repo (#3440) 2024-05-24 00:20:36 +00:00
docs Fix float32/float64 docs (#4779) 2024-10-17 20:34:26 +00:00
e2e Update prettier config to format trailing commas to `all` (Default) (#4457) 2024-09-16 20:20:57 +00:00
eng Update JS API parser version (#4750) 2024-10-17 20:23:18 +00:00
grammars Fix type argument tmlanguage (#4089) 2024-08-08 21:42:27 +00:00
icons/raw Website & Docs Cleanup (#3002) 2024-03-11 18:56:35 -07:00
packages Add blog back to astro (#4797) 2024-10-21 18:16:29 +00:00
.dockerignore Feature: docker image (#57) 2021-11-12 11:17:46 -08:00
.editorconfig Format CSharp files: add `dotnet format` to `rush format` (#490) 2022-04-29 09:46:23 -07:00
.gitattributes Add release notes for 0.56.0 (#3294) 2024-05-07 21:02:14 +00:00
.gitignore Merge 0.61.2 hotfix back into main (#4703) 2024-10-11 20:57:07 +00:00
.npmrc Add dev container configuration for repo (#3440) 2024-05-24 00:20:36 +00:00
.prettierignore Migrate website to astro [Step 1] (#4587) 2024-10-11 01:38:03 +00:00
.prettierrc.json Update prettier config to format trailing commas to `all` (Default) (#4457) 2024-09-16 20:20:57 +00:00
CODE_OF_CONDUCT.md Add LICENSE, CODE_OF_CONDUCT.md, and SECURITY.md 2021-10-19 14:53:13 -05:00
CONTRIBUTING.md Fix labels CI (#4336) 2024-09-04 17:58:53 +00:00
LICENSE Add LICENSE, CODE_OF_CONDUCT.md, and SECURITY.md 2021-10-19 14:53:13 -05:00
README.md Simplify Readme (#2864) 2024-01-30 16:18:37 -08:00
SECURITY.md Add LICENSE, CODE_OF_CONDUCT.md, and SECURITY.md 2021-10-19 14:53:13 -05:00
api-extractor.base.json Bump dependencies - Sep 2024 (#4424) 2024-09-13 15:50:22 +00:00
cspell.yaml Add blog back to astro (#4797) 2024-10-21 18:16:29 +00:00
eslint.config.js Migrate website to astro [Step 1] (#4587) 2024-10-11 01:38:03 +00:00
package.json Upgrade dependencies - October 2024 (#4679) 2024-10-10 16:54:34 +00:00
pnpm-lock.yaml Add blog back to astro (#4797) 2024-10-21 18:16:29 +00:00
pnpm-workspace.yaml Migrate python emitter (#4182) 2024-09-18 19:44:40 +00:00
troubleshooting.md 1/3 TypeSpec: Find/Replace Content 2023-02-16 13:07:22 -08:00
tsconfig.base.json Add numeric data structure (#3115) 2024-04-09 16:38:16 +00:00
tsconfig.eng.json Analyze change ts (#3415) 2024-07-26 18:38:09 +00:00
tsconfig.json Add storybook for playground library (#3412) 2024-05-24 02:37:11 +00:00
tsconfig.ws.json Migrate spec lib to spector (#4686) 2024-10-14 21:26:59 +00:00
vitest.config.ts Fix vitest not reloading JS files (#3395) 2024-05-17 21:53:01 +00:00
vitest.workspace.ts Fix anonymous union variant in tree viewer (#4353) 2024-09-05 17:45:19 +00:00

README.md

TypeSpec

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 many other assets. All this 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 makes 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 of the output to ensure it follows the patterns you want.

Installation

npm install -g @typespec/compiler

Tools

The TypeSpec VS Code extension can be installed from the VS Code marketplace or directly on the command line:

tsp code install

The TypeSpec VS Extension can be installed from the VS Marketplace or directly on the command line:

tsp vs install

Usage

TypeSpec to OpenAPI 3.0 Example

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 your main.tsp:

import "@typespec/http";
import "@typespec/rest";
import "@typespec/openapi3";

using TypeSpec.Http;
using TypeSpec.Rest;

/** This is a pet store service. */
@service({
  title: "Pet Store Service",
})
@server("https://example.com", "The service endpoint")
namespace PetStore;

@route("/pets")
interface Pets {
  list(): Pet[];
}

model Pet {
  @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.

Advanced Scenarios

Installing nightly version

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

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

After updating the package.json file you can run npm 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",
}

Packages

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 the main branch.