typespec: feedback from typespec team

Author: philsturgeon

openapi/frameworks/typespec.mdx

@@ -29,7 +29,7 @@ model Address {
 @route("/stores")
 interface Stores {
   list(@query filter: string): Store[];
-  read(@path id: Store): Store;
+  read(@path id: string): Store;
 }
 ```
 
@@ -130,7 +130,7 @@ Just like in TypeScript, code can be organized into files, folders, and modules,
 
 Here's an example of how to import files, folders, and modules in TypeSpec:
 
-```typescript filename="main.tsp"
+```typespec filename="main.tsp"
 import "./books.tsp"; // Import a file
 import "./books"; // Import main.tsp in a folder
 import "/books"; // Import a TypeSpec module's main.tsp file
@@ -142,7 +142,7 @@ Modules can be installed using npm, and the `import` statement imports them into
 
 Namespaces are defined using the `namespace` keyword, followed by the namespace name and a block of type definitions. Here's an example:
 
-```typescript
+```typespec
 namespace MyNamespace {
   model User {
     id: string;
@@ -153,7 +153,7 @@ namespace MyNamespace {
 
 They may also be defined at the file level, using the `namespace` keyword followed by the namespace name and a block of type definitions. Here's an example:
 
-```typescript
+```typespec
 namespace MyNamespace;
 
 model User {
@@ -172,7 +172,7 @@ model Post {
 
 [Models](https://typespec.io/docs/language-basics/models) in TypeSpec are similar to OpenAPI's `schema` objects. They define the structure of the data that will be sent and received by an API. Models are defined using the `model` keyword, followed by the model name and a block of properties. Here's an example:
 
-```typescript filename="main.tsp"
+```typespec filename="main.tsp"
 model User {
     id: string;
     name: string;
@@ -182,7 +182,7 @@ model User {
 
 Models are composable and extensible. Models can reference other models within a definition, extend a model with additional properties, and compose multiple models into a single model. Here's an example of model composition:
 
-```typescript filename="main.tsp"
+```typespec filename="main.tsp"
 namespace WithComposition {
     model User {
         id: string;
@@ -245,22 +245,22 @@ components:
 
 [Operations](https://typespec.io/docs/language-basics/operations) in TypeSpec are similar to OpenAPI operations. They describe the methods that users can call in an API. Operations are defined using the `op` keyword, followed by the operation name. Here's an example:
 
-```typescript filename="main.tsp"
-op listUsers(): User[]; // Defaults to GET
-op getUser(id: string): User; // Defaults to GET
-op createUser(@body user: User): User; // Defaults to POST with a body parameter
+```typespec filename="main.tsp"
+op list(): User[]; // Defaults to GET
+op read(id: string): User; // Defaults to GET
+op create(@body user: User): User; // Defaults to POST with a body parameter
 ```
 
 ### Interfaces in TypeSpec
 
 [Interfaces](https://typespec.io/docs/language-basics/interfaces) in TypeSpec group related operations together, similar to OpenAPI's `paths` object. Interfaces are defined using the `interface` keyword, followed by the interface name and a block of operations. Here's an example:
 
-```typescript filename="main.tsp"
+```typespec filename="main.tsp"
 @route("/users")
 interface Users {
-    op listUsers(): User[]; // Defaults to GET /users
-    op getUser(id: string): User; // Defaults to GET /users/{id}
-    op createUser(@body user: User): User; // Defaults to POST /users
+    op list(): User[]; // Defaults to GET /users
+    op read(id: string): User; // Defaults to GET /users/{id}
+    op create(@body user: User): User; // Defaults to POST /users
 }
 ```
 
@@ -317,7 +317,7 @@ paths:
 
 [Decorators](https://typespec.io/docs/language-basics/decorators) in TypeSpec add metadata to models, operations, and interfaces. They start with the `@` symbol followed by the decorator name. Here's an example of the `@doc` decorator:
 
-```typescript filename="main.tsp" mark=1,3,6,9
+```typespec filename="main.tsp" mark=1,3,6,9
 @doc("A user in the system")
 model User {
     @doc("The unique identifier of the user")
@@ -395,7 +395,7 @@ Open the `main.tsp` file in a text editor and write the TypeSpec specification.
 
 Here's an example of a complete TypeSpec file for a Train Travel API:
 
-```typescript
+```typespec
 import "@typespec/http";
 import "@typespec/openapi";
 import "@typespec/openapi3";
@@ -646,7 +646,7 @@ Let's break down some of the key features of this TypeSpec file:
 
 The file starts by importing necessary TypeSpec modules:
 
-```typescript
+```typespec
 import "@typespec/http";
 import "@typespec/openapi";
 import "@typespec/openapi3";
@@ -661,7 +661,7 @@ These modules extend TypeSpec's capabilities for HTTP APIs and OpenAPI generatio
 
 The `TrainTravelAPI` namespace is decorated with several metadata decorators:
 
-```typescript
+```typespec
 @service(#{ title: "Train Travel API" })
 @info(#{
   version: "1.2.1",
@@ -687,7 +687,7 @@ namespace TrainTravelAPI;
 
 TypeSpec supports various validation decorators for model properties:
 
-```typescript
+```typespec
 /** A train station. */
 model Station {
   /** Unique identifier for the station. */
@@ -714,7 +714,7 @@ The `@format` decorator adds format annotations (which some OpenAPI tools may ch
 
 Operations can return different response types using union types:
 
-```typescript
+```typespec
 op `get-stations`(...params):
   | {
       @body body: {
@@ -757,7 +757,7 @@ Using multiple examples like this requires OpenAPI v3.1 or later.
 
 The `Parameters` namespace defines reusable parameter models:
 
-```typescript
+```typespec
 namespace Parameters {
   model page {
     /** The page number to return */
@@ -781,7 +781,7 @@ TypeSpec supports polymorphism through unions with the `@oneOf` decorator, which
 
 Here's an example from the Train Travel API showing how to model payment sources that can be either a card or a bank account:
 
-```typescript
+```typespec
 /** Card payment source details. */
 model CardPaymentSource {
   object?: "card";
@@ -936,10 +936,11 @@ options:
   "@typespec/openapi3":
     emitter-output-dir: "{output-dir}/schema"
     openapi-versions:
+      - 3.1.0
       - 3.2.0
 ```
 
-This will configure TypeSpec to emit OpenAPI 3.2 specifically, which is a newer version of OpenAPI supported by both TypeSpec and Speakeasy. For an older version, change the `openapi-versions` value to `3.1.0`.
+This will configure TypeSpec to output both the more compatible OpenAPI v3.1, as well as the latest and greatest OpenAPI v3.2. This newer version is supported by TypeSpec and Speakeasy, and if you have older tools that need the more compatible version why not use both. 
 
 Now run the TypeSpec compiler in the project root to generate the OpenAPI document:
 
@@ -1138,7 +1139,7 @@ TypeSpec allows adding OpenAPI extensions using the `@extension` decorator. This
 
 To add retry logic to operations, add the Speakeasy `x-speakeasy-retries` extension to the TypeSpec specification:
 
-```typescript
+```typespec
 @tag("Stations")
 @route("/stations")
 @get
@@ -1182,6 +1183,23 @@ paths:
         retryConnectionErrors: true
 ```
 
+Or, the extension can be added at the namespace level: 
+
+```typespec name="main.tsp"
+@extension("x-speakeasy-retries", #{
+  strategy: "backoff",
+  backoff: #{
+    initialInterval: 500,
+    maxInterval: 60000,
+    maxElapsedTime: 3600000,
+    exponent: 1.5,
+  },
+  statusCodes: ["5XX"],
+  retryConnectionErrors: true
+})
+namespace TrainTravelAPI;
+```
+
 Similar extensions can be added for other Speakeasy features like [pagination](/docs/customize-sdks/pagination), [error handling](/docs/customize-sdks/error-handling), and more.
 
 ### Step 8: Generate an SDK from the OpenAPI Document
@@ -1220,17 +1238,10 @@ The `speakeasy run` command uses the existing Speakeasy configuration to regener
 
 ## Limitations of TypeSpec
 
-While TypeSpec is a powerful tool for generating OpenAPI documents, there are some limitations to be aware of when using it with Speakeasy.
-
-### 1. No Extensions at the Namespace Level
-
-The `x-speakeasy-retries` extension cannot be added at the namespace level in the TypeSpec specification, even though Speakeasy supports this extension at the operation level.
-
-The TypeSpec documentation on the [@extension](https://typespec.io/docs/libraries/openapi/reference/decorators#@TypeSpec.OpenAPI.extension) decorator does not mention any restrictions on where extensions can be applied, so this may be a bug or an undocumented limitation.
+An earlier version of this guide had a handful of concerns, but TypeSpec has progressed a long way in a short time, and now there is just the one problem we currently have.
 
-To work around this limitation, the `x-speakeasy-retries` extension can be added directly to the OpenAPI document using an overlay, as shown in the previous example, or by adding it to each operation individually in the TypeSpec specification**.**
 
-### 2. No Support for Webhooks or Callbacks
+### No Support for Webhooks or Callbacks
 
 TypeSpec [does not yet support webhooks or callbacks](https://github.com/microsoft/typespec/issues/4736), which are common in modern APIs. This means webhook operations or callback URLs cannot be defined in a TypeSpec specification and OpenAPI documents cannot be generated for them.
 

public/assets/openapi/typespec/main.tsp

@@ -25,6 +25,19 @@ using TypeSpec.Versioning;
 @versioned(Versions)
 @server("http://127.0.0.1:4010", "Book Store API v1")
 @doc("API for managing a book store inventory and orders")
+
+@extension("x-speakeasy-retries", #{
+  strategy: "backoff",
+  backoff: #{
+    initialInterval: 500,
+    maxInterval: 60000,
+    maxElapsedTime: 3600000,
+    exponent: 1.5,
+  },
+  statusCodes: ["5XX"],
+  retryConnectionErrors: true
+})
+
 namespace BookStore;
 
 enum Versions {
@@ -224,4 +237,4 @@ model Error {
 
   @doc("Error message")
   message: string;
-}
+}