Getting started

Getting started with TypeSpec migration

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

Important! Because TypeSpec is more expressive than OpenAPI 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 the appropriate repository based on your service type:
- RPSaaS service: Clone the repository where the latest version of your service spec resides — either azure-rest-api-specs-pr or azure-rest-api-specs.
- non-RPSaaS service: Clone azure-rest-api-specs.

Install dependencies:

npm install # Run at root of the repository

Generate TypeSpec with converter

Ensure your service folder structure follows the Specification Folder Structure Guide.
Go to the service folder
- control-plane: specification/{organization}/resource-manager/{resource-provider-namespace}/{service-name}.
- data-plan: specification/{organization}/data-plane/{service-name}.

Run the tool from the directory.

Convert a data-plane specification:

tsp-client convert --swagger-readme [path to readme.md]

Convert a control-plane specification:

tsp-client convert --swagger-readme [path to readme.md] --arm --fully-compatible

Review and adjust the TypeSpec

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

In the TypeSpec folder, compile TypeSpec files to emit an auto-generated OpenAPI file:
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}:
- For non-RPSaaS service (cloned from azure-rest-api-specs):
  Terminal window
```
.\eng\tools\typespec-migration-validation\scripts\download-main.ps1 {path\to\your\generated\openapi\file}
```
- For RPSaaS service (cloned from azure-rest-api-specs-pr):
  Terminal window
```
.\eng\tools\typespec-migration-validation\scripts\download-main.ps1 {path\to\your\generated\openapi\file} -isRPSaaSMaster $true
```
At the end of the console output, you’ll see the next command to sort, merge, and normalize the original OpenAPI file(s) and generated OpenAPI file, making it easier to review changes. Provide an outputFolder to store the analysis results:
Terminal window
```
npx tsmv {your\original\openapi\folder} {your\generated\openapi\file} --outputFolder {outputFolder}
```
In the {outputFolder}:
- newNormalizedSwagger.json is the processed version of the generated OpenAPI file
- oldNormalizedSwagger.json is the processed version of the original OpenAPI file(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 errors, warnings, suggested fixes, and prompts. Carefully review each item and take the appropriate action:
- Errors: These indicate issues that must be resolved before the migration can proceed. Address them before continuing.
- Warnings: These highlight potential problems that may affect correctness. Review each one and decide whether action is needed.
For remaining differences, follow this iterative process:
1. Recompile TypeSpec files with tsp compile . in the 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. Refer to Understanding the OpenAPI Changes to understand expected changes and mitigation steps.
Recommended order for fixing differences
For more effective visualization, fix differences in this order:
1. Path (route) differences first
2. Definition (model) name differences next
3. Detail differences within paths and definitions last

Once the TypeSpec-generated OpenAPI achieves functional equivalence with the original OpenAPI at the API level, add SDK emitter configurations to your tspconfig.yaml to validate that SDKs can be generated correctly from the TypeSpec.

Refer to the example at specification/widget/resource-manager/Microsoft.Widget/Widget/tspconfig.yaml in azure-rest-api-specs for the language-specific emitter options to add.

Create Spec PR with new TypeSpec project

In the readme.md file, under the latest tag, change the input-file to the OpenAPI file generated from TypeSpec.
If the generated OpenAPI file(s) for the latest version changed name, delete the old OpenAPI file(s) no longer referenced in README.md.
Create a PR with the TypeSpec files, changed OpenAPI files (examples included) and readme file.
Check CI failures. Refer to Resolving Pipeline failures

Canary Validation (RPSaaS service only)

If your service is an RPSaaS service, you must perform canary validation to verify the TypeSpec-generated spec works correctly before creating a PR. Follow the steps described in the Testing TypeSpec conversion in Canary documentation.

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.