Getting started

Getting started with TypeSpec migration

We have created a swagger to TypeSpec conversion tool to help take on the bulk of the manual conversion labor. It can handle both data-plane and management-plane swaggers. The produced TypeSpec relies on the Azure.Core and Azure.Resource.Manager libraries.

Important! Because TypeSpec is more expressive than Swagger and with the help of evolving Azure libraries, this tool should only be used as an aid in the conversion/migration process, not as the sole tool to produce final version of TypeSpec specs without human inspection, correction and optimization.

Steps of migration and comparison

Prerequisite

Clone azure-rest-api-specs.
Install dependencies:
Terminal window
```
npm install # Run at root
```

Generate TypeSpec with converter

Go to your specification/{service-name} folder in azure-rest-api-specs.
Create a directory holding TypeSpec files. See details here.
Run the tool from the directory.
- Convert a data-plane specification:
  Terminal window
```
tsp-client convert --swagger-readme [path to readme.md]
```
- Convert a control-plane specification:
  Terminal window
```
tsp-client convert --swagger-readme [path to readme.md] --arm
```
- Convert a control-plane specification to fully compatible output:
  
  By default, the converted TypeSpec project will leverage TypeSpec built-in libraries with standard patterns and templates (highly recommended), which will cause discrepancies between the generated TypeSpec and original swagger. If you really don’t want this intended discrepancy, add --fully-compatible flag to generate a TypeSpec project that is fully compatible with the swagger.
  Terminal window
```
tsp-client convert --swagger-readme [path to readme.md] --arm --fully-compatible
```

Review and adjust the TypeSpec

You will need to compare the Swagger generated from TypeSpec with your original Swagger specification(s) to ensure functional equivalence.

In your TypeSpec folder, compile your TypeSpec files to emit an auto-generated Swagger:
Terminal window
```
tsp compile .
```
From the root folder, download the latest specification as baseline. Your original specification will be located at .\sparse-spec\specification\{service-name}:
Terminal window
```
.\eng\tools\typespec-migration-validation\scripts\download-main.ps1 {path\to\your\generated\swagger}
```
At the end of the console output, you’ll see the next command to sort, merge, and normalize your original Swagger(s) and generated Swagger, making it easier to review changes. Provide an outputFolder to store the analysis results:
Terminal window
```
npx tsmv {your\original\swagger\folder} {your\generated\swagger\file} {outputFolder}
```
In the {outputFolder}:
- newNormalizedSwagger.json is the processed version of your generated Swagger
- oldNormalizedSwagger.json is the processed version of your original Swagger(s)
In VS Code, select both files (select oldNormalizedSwagger.json first, then newNormalizedSwagger.json), right-click and choose “Compare Selected”. Review these differences to understand their patterns.
Check out the output from npx tsmv execution. It prints suggested fixes and prompts if any. Please review them before any run.

Suggested fixes: These provide exact TypeSpec code that you can apply directly by following the instructions.

Suggested prompts: To use these, drag all your TypeSpec files into GitHub Copilot context. Select “Agent” or “Edit” mode with the “Claude” model. Use the provided prompt to ask GitHub Copilot to generate fixes. Carefully review all changes before accepting or undoing them.
For remaining differences, follow this iterative process:
1. Recompile your TypeSpec files with tsp compile . in your TypeSpec folder.
2. Run the npx tsmv command again with the same parameters.
3. Review the updated differences in VS Code.
4. Make further adjustments as needed. For more effective visualization, fix differences in this recommended order:
  - Path (route) differences first
  - Definition (model) name differences next
  - Detail differences within paths and definitions last

Create Spec PR with new TypeSpec project

Review CI checks such as breaking changes and other failures.

How to Get Help

Ask questions in the TypeSpec Discussions Channel
Attend TypeSpec office hours. The office hours is listed on top tabs on the discussion channel.
File issues in the typespec-azure github repo
- For bugs, please include:
  - A high-level description of the bug
  - Expected and Actual Results
  - Repro steps, including any TypeSpec code that you used
  - Any error messages you saw, including stack traces. For issues with VS or VS Code tooling see Troubleshooting VSCode Tooling and Filing Issues
Schedule review meetings with TypeSpec team.