swagger2teams

Introduction

This is a CLI tool to convert swagger yaml file to Teams App command bot project with adaptive cards based on TeamsFx.

Prerequisite

• Node.js, supported versions: 14, 16, 18
• A Microsoft 365 account. If you do not have Microsoft 365 account, apply one from Microsoft 365 developer program
• Latest stable Teams Toolkit Visual Studio Code Extension 4.x.x

Quick Start

• Install the CLI

  npm install swagger2teams@latest -g
  

• Clone and download sample swagger yaml files

  git clone https://github.com/SLdragon/test-swagger-yaml-files
  

• Go to test-swagger-yaml-files folder, and run the command below to convert test4.yml file to Teams App, it will generate teams project to generated-teams-app folder

  cd test-swagger-yaml-files
  swagger2teams test4.yml
  

• You can specify which folder to generate teams project as below

  swagger2teams test4.yml -o my-custom-teams-app-folder
  

• If you have other personal swagger yaml files, you can also use this CLI tool to covert them.

Run Generated Teams App

• Open generated folder in VSCode, and make sure you have installed Teams Toolkit (4.x.x).

• Click F5 in VSCode to run the Teams App to view the result (Below is the example of teams app converted by test4.yml file)

  • Send message GET /pets/1 to Bot, bot will send a response adaptive card:

    

  • Send message GET /pets to Bot, it will first send request a request adaptive card:

    

  • Input value in the request adaptive card, and then click GET button, it will send back response adaptive card:

    

  • Input url https://petstore.swagger.io/pets/1 inside message box, you can see the link unfurling:

    

Current Limitations

• Adaptive card doesn't support file upload, so if api contains file upload, then it cannot be converted to adaptive card

• For request card, there is no proper element to represent array type in adaptive card, so user need to input the array value manually

• It will not generate backend api calls due to swagger may contains auth, which is not easy to handle. So we will only provide a mock function and user need to manually update the mock to call real backend api.

• Some APIs may have conflict for the command trigger pattern. For example in test.yml file, GET /user/login and GET /user/{username} has conflict, the convert tool cannot easily to distinguish these two APIs.

• Do not support keyword oneOf, anyOf, not because there is no better ways to represent it in adaptive cards, only support allOf keyword

• Cannot remove link unfurling caches due to lack document about how to remove it, and there is an issue to track this: https://github.com/MicrosoftDocs/msteams-docs/issues/8108

• Command intellisense can only contain max 10 items due to Teams limitation

References

• Develop Doc
• Swagger Parser
• Swagger Samples