Sample: typespec-first-development - TypeSpec-first API workflow with LLM

samples/typespec-first-development/.devproxy/generate-typespec-llm.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v2.0.0/rc.schema.json",
+  "plugins": [
+    {
+      "name": "TypeSpecGeneratorPlugin",
+      "enabled": true,
+      "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll"
+    }
+  ],
+  "languageModel": {
+    "enabled": true,
+    "model": "llama3.2"
+  }
+}

samples/typespec-first-development/.devproxy/generate-typespec.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v2.0.0/rc.schema.json",
+  "plugins": [
+    {
+      "name": "TypeSpecGeneratorPlugin",
+      "enabled": true,
+      "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll"
+    }
+  ]
+}

samples/typespec-first-development/README.md

@@ -0,0 +1,130 @@
+# TypeSpec-first API development with LLM
+
+## Summary
+
+This sample demonstrates TypeSpec-first API development workflow using Dev Proxy. TypeSpec is a language for describing APIs that can generate OpenAPI specs, client SDKs, and server stubs. Using Dev Proxy's TypeSpecGeneratorPlugin, you can generate TypeSpec files from your API traffic and use a local language model to enhance the generated output with clearer operation IDs and descriptions.
+
+![Dev Proxy generating TypeSpec from API traffic](assets/screenshot.png)
+
+## Compatibility
+
+![Dev Proxy v2.0.0](https://aka.ms/devproxy/badge/v2.0.0)
+
+## Contributors
+
+- [Waldek Mastykarz](https://github.com/waldekmastykarz)
+
+## Version history
+
+Version|Date|Comments
+-------|----|--------
+1.0|January 10, 2026|Initial release
+
+## Minimal path to awesome
+
+### Generate TypeSpec without LLM
+
+1. Clone this repository (or [download this solution as a .ZIP file](https://pnp.github.io/download-partial/?url=https://github.com/pnp/proxy-samples/tree/main/samples/typespec-first-development) then unzip it)
+1. Start Dev Proxy with the basic configuration:
+
+   ```console
+   devproxy --config-file .devproxy/generate-typespec.json --urls-to-watch "https://jsonplaceholder.typicode.com/*" --record
+   ```
+
+1. In a new terminal, issue some API requests:
+
+   ```console
+   curl -ikx http://127.0.0.1:8000 https://jsonplaceholder.typicode.com/posts
+   curl -ikx http://127.0.0.1:8000 https://jsonplaceholder.typicode.com/posts/1
+   ```
+
+1. Stop Dev Proxy by pressing <kbd>Ctrl</kbd> + <kbd>C</kbd>
+1. Open the generated TypeSpec file in the current working folder
+
+### Generate TypeSpec with LLM (enhanced descriptions)
+
+> [!NOTE]
+> Using a local language model requires running a language model host like Ollama on your machine. By default, this configuration uses the `llama3.2` model. Ensure the model is running before starting Dev Proxy.
+
+1. Start your local language model host (e.g., Ollama with llama3.2)
+1. Start Dev Proxy with the LLM configuration:
+
+   ```console
+   devproxy --config-file .devproxy/generate-typespec-llm.json --urls-to-watch "https://jsonplaceholder.typicode.com/*" --record
+   ```
+
+1. In a new terminal, issue some API requests:
+
+   ```console
+   curl -ikx http://127.0.0.1:8000 https://jsonplaceholder.typicode.com/posts
+   curl -ikx http://127.0.0.1:8000 https://jsonplaceholder.typicode.com/posts/1
+   ```
+
+1. Stop Dev Proxy by pressing <kbd>Ctrl</kbd> + <kbd>C</kbd>
+1. Open the generated TypeSpec file with AI-enhanced descriptions
+
+## Features
+
+Using this sample, you can use Dev Proxy to:
+
+- **Generate TypeSpec from API traffic**: Record API requests and responses to automatically create TypeSpec files
+- **Enhance TypeSpec with LLM**: Use a local language model to generate clearer operation IDs and descriptions
+- **Kickstart TypeSpec-first development**: Use generated TypeSpec as a starting point for API design
+
+### Without LLM
+
+TypeSpec generated without LLM has basic operation names:
+
+```typescript
+@route("/posts")
+namespace Posts {
+  @get
+  op operation1(): Post[];
+
+  @get
+  @route("/{id}")
+  op operation2(@path id: int32): Post;
+}
+```
+
+### With LLM
+
+TypeSpec generated with LLM includes meaningful descriptions:
+
+```typescript
+@route("/posts")
+namespace Posts {
+  @doc("Retrieves a list of all posts")
+  @get
+  op getPosts(): Post[];
+
+  @doc("Retrieves a specific post by its unique identifier")
+  @get
+  @route("/{id}")
+  op getPostById(@path id: int32): Post;
+}
+```
+
+### Complete workflow
+
+The TypeSpec-first development workflow enables:
+
+1. **Record API traffic** → Generate TypeSpec file
+2. **TypeSpec** → Generate OpenAPI spec using TypeSpec compiler
+3. **OpenAPI** → Generate client SDKs for multiple languages
+
+## Help
+
+We do not support samples, but this community is always willing to help, and we want to improve these samples. We use GitHub to track issues, which makes it easy for community members to volunteer their time and help resolve issues.
+
+You can try looking at [issues related to this sample](https://github.com/pnp/proxy-samples/issues?q=label%3A%22sample%3A%20typespec-first-development%22) to see if anybody else is having the same issues.
+
+If you encounter any issues using this sample, [create a new issue](https://github.com/pnp/proxy-samples/issues/new).
+
+Finally, if you have an idea for improvement, [make a suggestion](https://github.com/pnp/proxy-samples/issues/new).
+
+## Disclaimer
+
+**THIS CODE IS PROVIDED *AS IS* WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING ANY IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR NON-INFRINGEMENT.**
+
+![](https://m365-visitor-stats.azurewebsites.net/SamplesGallery/pnp-devproxy-typespec-first-development)

samples/typespec-first-development/assets/README.md

@@ -0,0 +1,10 @@
+# Assets
+
+This folder should contain:
+
+- `screenshot.png` - A screenshot showing Dev Proxy generating TypeSpec from API traffic (recommended size: 1920x1080)
+
+The screenshot should ideally show:
+- Dev Proxy running in record mode
+- The generated TypeSpec file output
+- Optionally, a comparison between output with and without LLM

samples/typespec-first-development/assets/sample.json

@@ -0,0 +1,82 @@
+[
+  {
+    "name": "pnp-devproxy-typespec-first-development",
+    "source": "pnp",
+    "title": "TypeSpec-first API development with LLM",
+    "shortDescription": "This sample demonstrates TypeSpec-first API development workflow using Dev Proxy. Generate TypeSpec files from API traffic and use a local language model to enhance the output with clearer operation IDs and descriptions.",
+    "url": "https://github.com/pnp/proxy-samples/tree/main/samples/typespec-first-development",
+    "downloadUrl": "https://pnp.github.io/download-partial/?url=https://github.com/pnp/proxy-samples/tree/main/samples/typespec-first-development",
+    "longDescription": [
+      "This sample demonstrates TypeSpec-first API development workflow using Dev Proxy. Generate TypeSpec files from API traffic and use a local language model to enhance the output with clearer operation IDs and descriptions."
+    ],
+    "creationDateTime": "2026-01-10",
+    "updateDateTime": "2026-01-10",
+    "products": [
+      "Dev Proxy"
+    ],
+    "metadata": [
+      {
+        "key": "SAMPLE ID",
+        "value": "typespec-first-development"
+      },
+      {
+        "key": "PRESET",
+        "value": "Yes"
+      },
+      {
+        "key": "MOCKS",
+        "value": "No"
+      },
+      {
+        "key": "PLUGIN",
+        "value": "No"
+      },
+      {
+        "key": "PROXY VERSION",
+        "value": "v2.0.0"
+      }
+    ],
+    "thumbnails": [
+      {
+        "type": "image",
+        "order": 100,
+        "url": "https://github.com/pnp/proxy-samples/raw/main/samples/typespec-first-development/assets/screenshot.png",
+        "alt": "Dev Proxy generating TypeSpec from API traffic"
+      }
+    ],
+    "authors": [
+      {
+        "gitHubAccount": "waldekmastykarz",
+        "pictureUrl": "https://github.com/waldekmastykarz.png",
+        "name": "Waldek Mastykarz"
+      }
+    ],
+    "references": [
+      {
+        "name": "Get started with Dev Proxy",
+        "description": "The tutorial will introduce you to Dev Proxy and show you how to use its features.",
+        "url": "https://learn.microsoft.com/microsoft-cloud/dev/dev-proxy/get-started"
+      },
+      {
+        "name": "Generate a TypeSpec file",
+        "description": "Learn how to use Dev Proxy to generate a TypeSpec file from intercepted API traffic.",
+        "url": "https://learn.microsoft.com/microsoft-cloud/dev/dev-proxy/how-to/generate-typespec-file"
+      },
+      {
+        "name": "TypeSpecGeneratorPlugin",
+        "description": "Technical reference for the TypeSpecGeneratorPlugin that generates TypeSpec files from API traffic.",
+        "url": "https://learn.microsoft.com/microsoft-cloud/dev/dev-proxy/technical-reference/typespecgeneratorplugin"
+      },
+      {
+        "name": "Use a local language model",
+        "description": "Learn how to use a local language model with Dev Proxy to enhance generated output.",
+        "url": "https://learn.microsoft.com/microsoft-cloud/dev/dev-proxy/how-to/use-language-model"
+      },
+      {
+        "name": "Use preset configurations",
+        "description": "Instructions on how to configure Dev Proxy to use a different configuration file.",
+        "url": "https://learn.microsoft.com/microsoft-cloud/dev/dev-proxy/how-to/use-preset-configurations"
+      }
+    ]
+  }
+]