swagger2teams

Introduction

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

Get start

• Make sure your NodeJS version >= 14

• Install the CLI

  npm install swagger2teams -g
  

• If you don't have any swagger yaml file, you can download some sample yaml files here: https://github.com/SLdragon/test-swagger-yaml-files

• Run the convert tool, it will generate teams project to generated-teams-app folder

  swagger2teams test4.yml
  

• You can also specify which folder to generate teams project

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

• 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 project to view the result (Use this yaml file as example: https://github.com/SLdragon/test-swagger-yaml-files/blob/master/test4.yml):

  • 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://www.swagger.io/pets/1 (Note: currently base URL can only be https://*.swagger.io) 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

Detailed document

Develop Doc