From cc5ca020ca00a5c6b98809e89aacec52a3e789bd Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 6 Jan 2026 11:35:46 +0000 Subject: [PATCH 1/6] Initial plan From 5e69cf88d3ea6cec8aa909dc19e158f7e11dd10b Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 6 Jan 2026 12:00:39 +0000 Subject: [PATCH 2/6] Add typespec-first-development sample with basic and LLM configurations Co-authored-by: waldekmastykarz <11164679+waldekmastykarz@users.noreply.github.com> --- samples/typespec-first-development/README.md | 134 ++++++++++++++++++ .../assets/README.md | 10 ++ .../assets/sample.json | 82 +++++++++++ .../generate-typespec-llm.json | 15 ++ .../generate-typespec.json | 11 ++ 5 files changed, 252 insertions(+) create mode 100644 samples/typespec-first-development/README.md create mode 100644 samples/typespec-first-development/assets/README.md create mode 100644 samples/typespec-first-development/assets/sample.json create mode 100644 samples/typespec-first-development/generate-typespec-llm.json create mode 100644 samples/typespec-first-development/generate-typespec.json diff --git a/samples/typespec-first-development/README.md b/samples/typespec-first-development/README.md new file mode 100644 index 0000000..b3fa97a --- /dev/null +++ b/samples/typespec-first-development/README.md @@ -0,0 +1,134 @@ +# 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 + +- [GitHub Copilot](https://github.com/copilot) + +## Version history + +Version|Date|Comments +-------|----|-------- +1.0|January 6, 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, specifying your API URL: + + ```console + devproxy --config-file generate-typespec.json --urls-to-watch "https://api.contoso.com/*" --record + ``` + +1. Use your application to issue API requests +1. Stop Dev Proxy by pressing Ctrl + C +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 generate-typespec-llm.json --urls-to-watch "https://api.contoso.com/*" --record + ``` + +1. Use your application to issue API requests +1. Stop Dev Proxy by pressing Ctrl + C +1. Open the generated TypeSpec file with AI-enhanced descriptions + +### Test with a sample API + +You can test the TypeSpec generation using the JSON Placeholder API: + +```bash +# Start Dev Proxy with recording +devproxy --config-file generate-typespec.json --urls-to-watch "https://jsonplaceholder.typicode.com/*" --record + +# In another terminal, make sample requests +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 +curl -ikx http://127.0.0.1:8000 https://jsonplaceholder.typicode.com/users + +# Stop Dev Proxy (Ctrl+C) to generate the TypeSpec file +``` + +## 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) diff --git a/samples/typespec-first-development/assets/README.md b/samples/typespec-first-development/assets/README.md new file mode 100644 index 0000000..14415d4 --- /dev/null +++ b/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 diff --git a/samples/typespec-first-development/assets/sample.json b/samples/typespec-first-development/assets/sample.json new file mode 100644 index 0000000..195331b --- /dev/null +++ b/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-06", + "updateDateTime": "2026-01-06", + "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": "copilot", + "pictureUrl": "https://github.com/copilot.png", + "name": "GitHub Copilot" + } + ], + "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" + } + ] + } +] diff --git a/samples/typespec-first-development/generate-typespec-llm.json b/samples/typespec-first-development/generate-typespec-llm.json new file mode 100644 index 0000000..91dcdfe --- /dev/null +++ b/samples/typespec-first-development/generate-typespec-llm.json @@ -0,0 +1,15 @@ +{ + "$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" + }, + "rate": 0 +} diff --git a/samples/typespec-first-development/generate-typespec.json b/samples/typespec-first-development/generate-typespec.json new file mode 100644 index 0000000..b87eb74 --- /dev/null +++ b/samples/typespec-first-development/generate-typespec.json @@ -0,0 +1,11 @@ +{ + "$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" + } + ], + "rate": 0 +} From 326aba57e894300e28bf6a1b30cba37206c52493 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 10 Jan 2026 08:32:11 +0000 Subject: [PATCH 3/6] Update sample to comply with repository guidelines Co-authored-by: waldekmastykarz <11164679+waldekmastykarz@users.noreply.github.com> --- samples/typespec-first-development/README.md | 17 +---------------- .../assets/sample.json | 2 +- 2 files changed, 2 insertions(+), 17 deletions(-) diff --git a/samples/typespec-first-development/README.md b/samples/typespec-first-development/README.md index b3fa97a..deab210 100644 --- a/samples/typespec-first-development/README.md +++ b/samples/typespec-first-development/README.md @@ -18,6 +18,7 @@ This sample demonstrates TypeSpec-first API development workflow using Dev Proxy Version|Date|Comments -------|----|-------- +1.1|January 10, 2026|Updated to comply with repository guidelines 1.0|January 6, 2026|Initial release ## Minimal path to awesome @@ -51,22 +52,6 @@ Version|Date|Comments 1. Stop Dev Proxy by pressing Ctrl + C 1. Open the generated TypeSpec file with AI-enhanced descriptions -### Test with a sample API - -You can test the TypeSpec generation using the JSON Placeholder API: - -```bash -# Start Dev Proxy with recording -devproxy --config-file generate-typespec.json --urls-to-watch "https://jsonplaceholder.typicode.com/*" --record - -# In another terminal, make sample requests -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 -curl -ikx http://127.0.0.1:8000 https://jsonplaceholder.typicode.com/users - -# Stop Dev Proxy (Ctrl+C) to generate the TypeSpec file -``` - ## Features Using this sample, you can use Dev Proxy to: diff --git a/samples/typespec-first-development/assets/sample.json b/samples/typespec-first-development/assets/sample.json index 195331b..b5e2eda 100644 --- a/samples/typespec-first-development/assets/sample.json +++ b/samples/typespec-first-development/assets/sample.json @@ -10,7 +10,7 @@ "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-06", - "updateDateTime": "2026-01-06", + "updateDateTime": "2026-01-10", "products": [ "Dev Proxy" ], From 50bed569bbe988ca95ffa060951a7129b624984a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 10 Jan 2026 10:13:48 +0000 Subject: [PATCH 4/6] Update author and dates per feedback Co-authored-by: waldekmastykarz <11164679+waldekmastykarz@users.noreply.github.com> --- samples/typespec-first-development/README.md | 5 ++--- samples/typespec-first-development/assets/sample.json | 8 ++++---- 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/samples/typespec-first-development/README.md b/samples/typespec-first-development/README.md index deab210..de5c2bb 100644 --- a/samples/typespec-first-development/README.md +++ b/samples/typespec-first-development/README.md @@ -12,14 +12,13 @@ This sample demonstrates TypeSpec-first API development workflow using Dev Proxy ## Contributors -- [GitHub Copilot](https://github.com/copilot) +- [Waldek Mastykarz](https://github.com/waldekmastykarz) ## Version history Version|Date|Comments -------|----|-------- -1.1|January 10, 2026|Updated to comply with repository guidelines -1.0|January 6, 2026|Initial release +1.0|January 10, 2026|Initial release ## Minimal path to awesome diff --git a/samples/typespec-first-development/assets/sample.json b/samples/typespec-first-development/assets/sample.json index b5e2eda..7d04e87 100644 --- a/samples/typespec-first-development/assets/sample.json +++ b/samples/typespec-first-development/assets/sample.json @@ -9,7 +9,7 @@ "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-06", + "creationDateTime": "2026-01-10", "updateDateTime": "2026-01-10", "products": [ "Dev Proxy" @@ -46,9 +46,9 @@ ], "authors": [ { - "gitHubAccount": "copilot", - "pictureUrl": "https://github.com/copilot.png", - "name": "GitHub Copilot" + "gitHubAccount": "waldekmastykarz", + "pictureUrl": "https://github.com/waldekmastykarz.png", + "name": "Waldek Mastykarz" } ], "references": [ From 870a6518531ed14f1e741575b81b13d8646f4631 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 10 Jan 2026 14:53:03 +0000 Subject: [PATCH 5/6] Move config files to .devproxy folder and remove default values Co-authored-by: waldekmastykarz <11164679+waldekmastykarz@users.noreply.github.com> --- .../{ => .devproxy}/generate-typespec-llm.json | 3 +-- .../{ => .devproxy}/generate-typespec.json | 3 +-- samples/typespec-first-development/README.md | 4 ++-- 3 files changed, 4 insertions(+), 6 deletions(-) rename samples/typespec-first-development/{ => .devproxy}/generate-typespec-llm.json (95%) rename samples/typespec-first-development/{ => .devproxy}/generate-typespec.json (93%) diff --git a/samples/typespec-first-development/generate-typespec-llm.json b/samples/typespec-first-development/.devproxy/generate-typespec-llm.json similarity index 95% rename from samples/typespec-first-development/generate-typespec-llm.json rename to samples/typespec-first-development/.devproxy/generate-typespec-llm.json index 91dcdfe..592aa7e 100644 --- a/samples/typespec-first-development/generate-typespec-llm.json +++ b/samples/typespec-first-development/.devproxy/generate-typespec-llm.json @@ -10,6 +10,5 @@ "languageModel": { "enabled": true, "model": "llama3.2" - }, - "rate": 0 + } } diff --git a/samples/typespec-first-development/generate-typespec.json b/samples/typespec-first-development/.devproxy/generate-typespec.json similarity index 93% rename from samples/typespec-first-development/generate-typespec.json rename to samples/typespec-first-development/.devproxy/generate-typespec.json index b87eb74..3116be9 100644 --- a/samples/typespec-first-development/generate-typespec.json +++ b/samples/typespec-first-development/.devproxy/generate-typespec.json @@ -6,6 +6,5 @@ "enabled": true, "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll" } - ], - "rate": 0 + ] } diff --git a/samples/typespec-first-development/README.md b/samples/typespec-first-development/README.md index de5c2bb..77f0a67 100644 --- a/samples/typespec-first-development/README.md +++ b/samples/typespec-first-development/README.md @@ -28,7 +28,7 @@ Version|Date|Comments 1. Start Dev Proxy with the basic configuration, specifying your API URL: ```console - devproxy --config-file generate-typespec.json --urls-to-watch "https://api.contoso.com/*" --record + devproxy --config-file .devproxy/generate-typespec.json --urls-to-watch "https://api.contoso.com/*" --record ``` 1. Use your application to issue API requests @@ -44,7 +44,7 @@ Version|Date|Comments 1. Start Dev Proxy with the LLM configuration: ```console - devproxy --config-file generate-typespec-llm.json --urls-to-watch "https://api.contoso.com/*" --record + devproxy --config-file .devproxy/generate-typespec-llm.json --urls-to-watch "https://api.contoso.com/*" --record ``` 1. Use your application to issue API requests From 6b89b1892d06f2410ce7a22fc22f8979c25508e5 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 17 Jan 2026 11:18:15 +0000 Subject: [PATCH 6/6] Use JSONPlaceholder API in README examples Co-authored-by: waldekmastykarz <11164679+waldekmastykarz@users.noreply.github.com> --- samples/typespec-first-development/README.md | 22 +++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/samples/typespec-first-development/README.md b/samples/typespec-first-development/README.md index 77f0a67..ff0dd7b 100644 --- a/samples/typespec-first-development/README.md +++ b/samples/typespec-first-development/README.md @@ -25,13 +25,19 @@ Version|Date|Comments ### 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, specifying your API URL: +1. Start Dev Proxy with the basic configuration: ```console - devproxy --config-file .devproxy/generate-typespec.json --urls-to-watch "https://api.contoso.com/*" --record + 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. Use your application to issue API requests 1. Stop Dev Proxy by pressing Ctrl + C 1. Open the generated TypeSpec file in the current working folder @@ -44,10 +50,16 @@ Version|Date|Comments 1. Start Dev Proxy with the LLM configuration: ```console - devproxy --config-file .devproxy/generate-typespec-llm.json --urls-to-watch "https://api.contoso.com/*" --record + 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. Use your application to issue API requests 1. Stop Dev Proxy by pressing Ctrl + C 1. Open the generated TypeSpec file with AI-enhanced descriptions