@microsoft/api2teams

Welcome to api2teams

The api2teams and its generated project template is currently under active development. Report any issues to us here

api2teams is a command line tool to generate a complete conversational style command and response Teams application based on your Open API specification file and represent the API response in the form of Adaptive Cards.

api2teams is the best way to start integrating your APIs with Teams conversational experience.

Prerequisite

Before running this CLI and deploying your generated Teams App to Azure or your local development machine, please ensure that you have the following prerequisites in place:

• Node.js, supported versions: 14, 16, 18
• An Microsoft 365 account for development
• Teams Toolkit Visual Studio Code Extension version 5.0.0 and higher or TeamsFx CLI
• [Option] If you want to deploy this APP to Azure, you also need an Azure subscription. If you don't have an Azure subscription, create a free account before you begin

Quick start

• Install api2teams with npm: npm install @microsoft/api2teams@latest -g
• Prepare the Open API specification. If you don't currently have one, start with a sample we provided by saving a copy of the sample-open-api-spec.yml to your local disk.
• Convert the Open API spec to a Teams app, assuming you are using the sample-open-api-spec.yml: api2teams sample-open-api-spec.yml

Available commands and options

The CLI name is api2teams. Usage is as below:

Usage: api2teams [options] <yaml>

Convert open api spec file to Teams APP project, only for GET operation

Arguments:
  yaml                   yaml file path to convert

Options:
  -o, --output [string]  output folder for teams app (default: "./generated-teams-app")
  -f, --force            force overwrite the output folder
  -v, --version          output the current version
  -h, --help             display help for command

You can input below command to generate Teams App to default or specific folder:

api2teams sample-open-api-spec.yml # generate teams app to default folder ./generated-teams-app
api2teams sample-open-api-spec.yml -o ./my-app # generate teams app to ./my-app folder
api2teams sample-open-api-spec.yml -o ./my-app -f # generate teams app to ./my-app folder, and force overwrite output folder
api2teams -h # show help message
api2teams -v # show version information

Getting started with the generated Teams app

• Open the generated project in Visual Studio Code and make sure you have the latest Teams Toolkit (version 5.0.0 or higher) installed.

• Follow the instruction provided in the README.md for the generated project to get started. For the Teams app converted by the given sample Open API spec, you will be able to run a GET /pets/1 command in Teams and a bot will return an Adaptive Card as response.

  

Current limitations

1. The api2teams doesn't support Open API schema version < 3.0.0.
2. The api2teams doesn't support Authorization property in Open API specification.
3. The api2teams doesn't support webhooks property and it would be ignored during convert.
4. The api2teams doesn't support oneOf, anyOf, notkeyword (It only support allOf keyword currently).
5. The api2teams doesn't support POST, PUT, PATCH or DELETE operations (It only supports GET operation currently).
6. The generated Adaptive Card doesn't support array type.
7. The generated Adaptive Card doesn't support file upload.
8. The generated Teams app can only contain up to 10 items in the command menu.

Further reading

• Teams Toolkit
• Teams Platform Developer Documentation
• Adaptive Card Designer
• Swagger Parser
• Swagger Samples