feat: adds dependencies filter documentation (#110)

* feat: adds dependencies filter documentation

Signed-off-by: Vincent Biret <[email protected]>

* fix: formats as table

Signed-off-by: Vincent Biret <[email protected]>

* adds a language to the example

Signed-off-by: Vincent Biret <[email protected]>

* docs: adds dependencies topic

Signed-off-by: Vincent Biret <[email protected]>

* chore: adds kiota as a known word

Signed-off-by: Vincent Biret <[email protected]>

* feat: updates quick start to use bundles

Signed-off-by: Vincent Biret <[email protected]>

* fix: adds s and ds arguments for java to workaround dependency management and migration command

Signed-off-by: Vincent Biret <[email protected]>

---------

Signed-off-by: Vincent Biret <[email protected]>

.vscode/settings.json

@@ -2,5 +2,8 @@
     "cSpell.spellCheckOnlyWorkspaceFiles": true,
     "markdownlint.ignore": [
         "LICENSE-CODE"
-    ]
+    ],
+  "cSpell.words": [
+    "kiota"
+  ]
 }

OpenAPI/kiota/dependencies.md

@@ -0,0 +1,206 @@
+---
+title: Managing dependencies of Kiota API clients
+description: Learn what different dependencies bring to your project and how to manage them.
+author: baywet
+ms.author: vibiret
+ms.topic: conceptual
+date: 03/21/2023
+---
+
+# Managing dependencies of Kiota API clients
+
+Kiota clients require multiple dependencies to function properly. In this documentation page you'll find details about each dependency, which package to use in each language and guidance on how to properly manage these dependencies for your application.
+
+## Guidance
+
+### Generated client and dependencies versions alignment
+
+For the best experience, after generating or updating a client, always ensure the kiota dependencies are aligned with the versions recommended by the info command.
+
+[More information about the info command](./using.md#language-information)
+
+### Dependencies selection
+
+In most cases, the [bundle](#bundle) package and any [additionally required package](#additional) for the language you are using will bring most dependencies your application needs.
+
+If your application requires a specific [HTTP](#http) client, [serialization](#serialization) library or format, you'll need to at least add the abstractions and additionally required dependencies for the language you're using. Additionally, you can select default implementations for HTTP and serialization packages, or swap them for third party or your own implementations.
+
+Additionally, your application might need to reference an [authentication](#authentication) package depending on the target API.
+
+## Abstractions
+
+Any Kiota generated API client relies on a set of abstractions as a build and runtime dependency, the application will require this dependency after a new client is generated.
+
+[More information about the abstractions package](./abstractions.md)
+
+The following table provides the list of abstractions package per language.
+
+| Language | Package Name |
+| -------- | ------------ |
+| C# | Microsoft.Kiota.Abstractions |
+| CLI | Microsoft.Kiota.Abstractions |
+| Go | github.com/microsoft/kiota-abstractions-go |
+| Java | com.microsoft.kiota:microsoft-kiota-abstractions |
+| PHP | microsoft/kiota-abstractions |
+| Python | microsoft-kiota-abstractions |
+| Ruby | microsoft_kiota_abstractions |
+| Swift | Not released |
+| TypeScript | @microsoft/kiota-abstractions |
+
+## Serialization
+
+Kiota provides default implementation for diverse serialization formats. These dependencies are required at runtime. Depending the the application requirements those implementations can be used as is, swapped or augmented with implementations from the application, or swapped with third party implementations.
+
+[More information about the serialization packages](./serialization.md)
+
+### JSON
+
+Media type: application/json
+
+The following table provides the list of serialization package per language.
+
+| Language | Package Name | Relies on |
+| -------- | ------------ | --------- |
+| C# | Microsoft.Kiota.Serialization.Json | System.Text.Json |
+| CLI | Microsoft.Kiota.Serialization.Json | System.Text.Json |
+| Go | github.com/microsoft/kiota-serialization-json-go | None |
+| Java | com.microsoft.kiota:microsoft-kiota-serialization-json | Gson |
+| PHP | microsoft/kiota-serialization-json | None |
+| Python | microsoft-kiota-serialization-json | None |
+| Ruby | microsoft_kiota_serialization_json | None |
+| Swift | Not released | None |
+| TypeScript | @microsoft/kiota-serialization-json | None |
+
+### Multipart
+
+Media type: multipart/form-data
+
+The following table provides the list of serialization package per language.
+
+| Language | Package Name | Relies on |
+| -------- | ------------ | --------- |
+| C# | Microsoft.Kiota.Serialization.Multipart | None |
+| CLI | Microsoft.Kiota.Serialization.Multipart | None |
+| Go | github.com/microsoft/kiota-serialization-multipart-go | None |
+| Java | com.microsoft.kiota:microsoft-kiota-serialization-multipart | None |
+| PHP | microsoft/kiota-serialization-multipart | None |
+| Python | microsoft-kiota-serialization-multipart | None |
+| Ruby | Not released | None |
+| Swift | Not released | None |
+| TypeScript | @microsoft/kiota-serialization-multipart | None |
+
+### Form
+
+Media type: application/x-www-form-urlencoded
+
+The following table provides the list of serialization package per language.
+
+| Language | Package Name | Relies on |
+| -------- | ------------ | --------- |
+| C# | Microsoft.Kiota.Serialization.Form | None |
+| CLI | Microsoft.Kiota.Serialization.Form | None |
+| Go | github.com/microsoft/kiota-serialization-form-go | None |
+| Java | com.microsoft.kiota:microsoft-kiota-serialization-form | None |
+| PHP | microsoft/kiota-serialization-form | None |
+| Python | microsoft-kiota-serialization-form | None |
+| Ruby | Not Released | None |
+| Swift | Not released | None |
+| TypeScript | @microsoft/kiota-serialization-form | None |
+
+### Text
+
+Media type: text/plain
+
+The following table provides the list of serialization package per language.
+
+| Language | Package Name | Relies on |
+| -------- | ------------ | --------- |
+| C# | Microsoft.Kiota.Serialization.Text | None |
+| CLI | Microsoft.Kiota.Serialization.Text | None |
+| Go | github.com/microsoft/kiota-serialization-text-go | None |
+| Java | com.microsoft.kiota:microsoft-kiota-serialization-text | None |
+| PHP | microsoft/kiota-serialization-text | None |
+| Python | microsoft-kiota-serialization-text | None |
+| Ruby | Not Released | None |
+| Swift | Not released | None |
+| TypeScript | @microsoft/kiota-serialization-text | None |
+
+## Http
+
+Kiota provides a default request adapter implementation to convert abstract request information objects created by the generated fluent API to HTTP requests. This dependency is required at runtime. Depending the the application requirements this implementation can be used as is, swapped with another implementation from the application, or swapped with a third party implementation.
+
+[More information about the HTTP package](./middleware.md).
+
+The following table provides the list of HTTP package per language.
+
+| Language | Package Name | Relies on |
+| -------- | ------------ | --------- |
+| C# | Microsoft.Kiota.Http.HttpClientLibrary | System.Net.Http |
+| CLI | Microsoft.Kiota.Http.HttpClientLibrary | System.Net.Http |
+| Go | github.com/microsoft/kiota-http-go | net/http |
+| Java | com.microsoft.kiota:microsoft-kiota-http-okHttp | None |
+| PHP | microsoft/kiota-http-guzzle | None |
+| Python | microsoft-kiota-http | None |
+| Ruby | microsoft_kiota_faraday | None |
+| Swift | Not released | None |
+| TypeScript | @microsoft/kiota-http-fetchlibrary | None |
+
+## Authentication
+
+Depending on authentication requirements from the target REST APIs, your application might additionally need an authentication dependency. Kiota provides default implementation providers for specific scenarios. Depending the the application requirements those implementations can be used as is, swapped or augmented with implementations from the application, or swapped with third party implementations.
+
+[More information about the authentication package](./authentication.md)
+
+### Azure Identity
+
+These providers might be used for any API secured with Bearer token authorization for which the identity platform is Entra Identity/Microsoft Identity Platform/Azure Identity/Azure Active Directory.
+
+The following table provides the list of authentication package per language.
+
+| Language | Package Name | Relies on |
+| -------- | ------------ | --------- |
+| C# | Microsoft.Kiota.Authentication.Azure | Azure.Identity |
+| CLI | Microsoft.Kiota.Authentication.Azure | Azure.Identity |
+| Go | github.com/microsoft/kiota-authentication-azure-go | github.com/Azure/azure-sdk-for-go/sdk/azidentity |
+| Java | com.microsoft.kiota:microsoft-kiota-authentication-azure | com.azure:azure-identity |
+| PHP | microsoft/kiota-authentication-phpleague | phpleague |
+| Python | microsoft-kiota-authentication-azure | azure-identity |
+| Ruby | microsoft_kiota_authentication_oauth | oauth |
+| Swift | Not released | None |
+| TypeScript | @microsoft/kiota-authentication-azure | @azure/identity |
+
+## Additional
+
+Additional dependencies are required at build time and/or runtime.
+
+The following table provides the list of additional package per language.
+
+| Language | Package Name | Type |
+| -------- | ------------ | ---- |
+| C# | None | |
+| CLI | Microsoft.Kiota.CLI.Commons, System.CommandLine | Build and runtime |
+| Go | None | |
+| Java | jakarta.annotation:jakarta.annotation-api:2.0.0 | Build |
+| PHP | None | |
+| Python | None | |
+| Ruby | None | |
+| Swift | None | |
+| TypeScript | None | |
+
+## Bundle
+
+To simplify dependencies management, kiota now offers bundles which contains abstractions, the default serialization implementations, and the default http implementation. Bundle packages can be used as an alternative to adding references to those packages.
+
+The following table provides the list of bundle package per language.
+
+| Language | Package Name |
+| -------- | ------------ |
+| C# | Microsoft.Kiota.Bundle |
+| CLI | Microsoft.Kiota.Bundle |
+| Go | github.com/microsoft/kiota-bundle-go |
+| Java | com.microsoft.kiota:microsoft-kiota-bundle |
+| PHP | Not available |
+| Python | Not available |
+| Ruby | Not available |
+| Swift | Not available |
+| TypeScript | @microsoft/kiota-bundle |

OpenAPI/kiota/quickstarts/cli.md

@@ -38,26 +38,15 @@ In case you're adding a Kiota client to an existing project, the following confi
 
 ## Add dependencies
 
-Before you can compile and run the generated API client, you need to make sure the generated source files are part of a project with the required dependencies. Your project must have a reference to the [abstraction package](https://github.com/microsoft/kiota-abstractions-dotnet) and the [cli-commons package](https://github.com/microsoft/kiota-cli-commons). Additionally, you must either use the Kiota default implementations or provide your own custom implementations of the following packages.
-
-- HTTP ([Kiota default HttpClient-based implementation](https://github.com/microsoft/kiota-http-dotnet))
-- Form serialization ([Kiota default](https://github.com/microsoft/kiota-serialization-form-dotnet))
-- JSON serialization ([Kiota default](https://github.com/microsoft/kiota-serialization-json-dotnet))
-- Text serialization ([Kiota default](https://github.com/microsoft/kiota-serialization-text-dotnet))
-- Multipart serialization ([Kiota default](https://github.com/microsoft/kiota-serialization-multipart-dotnet))
+Before you can compile and run the generated API client, you need to make sure the generated source files are part of a project with the required dependencies. Your project must have a reference to the [bundle package](https://github.com/microsoft/kiota-dotnet) and the [cli-commons package](https://github.com/microsoft/kiota-cli-commons). For more information about kiota dependencies, refer to [the dependencies documentation](../dependencies.md).
 
 For this tutorial, use the default implementations.
 
 Run the following commands to get the required dependencies.
 
 ```bash
-dotnet add package Microsoft.Kiota.Abstractions
+dotnet add package Microsoft.Kiota.Bundle
 dotnet add package Microsoft.Kiota.Cli.Commons --prerelease
-dotnet add package Microsoft.Kiota.Http.HttpClientLibrary
-dotnet add package Microsoft.Kiota.Serialization.Form
-dotnet add package Microsoft.Kiota.Serialization.Json
-dotnet add package Microsoft.Kiota.Serialization.Text
-dotnet add package Microsoft.Kiota.Serialization.Multipart
 ```
 
 ## Generate the API client

OpenAPI/kiota/quickstarts/dotnet.md

@@ -37,25 +37,12 @@ The following configuration is recommended:
 
 ## Add dependencies
 
-Before you can compile and run the generated API client, you need to make sure the generated source files are part of a project with the required dependencies. Your project must have a reference to the [abstraction package](https://github.com/microsoft/kiota-abstractions-dotnet). Additionally, you must either use the Kiota default implementations or provide your own custom implementations of the following packages.
-
-- HTTP ([Kiota default HttpClient-based implementation](https://github.com/microsoft/kiota-http-dotnet))
-- Form serialization ([Kiota default](https://github.com/microsoft/kiota-serialization-form-dotnet))
-- JSON serialization ([Kiota default](https://github.com/microsoft/kiota-serialization-json-dotnet))
-- Text serialization ([Kiota default](https://github.com/microsoft/kiota-serialization-text-dotnet))
-- Multipart serialization ([Kiota default](https://github.com/microsoft/kiota-serialization-multipart-dotnet))
-
-For this tutorial, use the default implementations.
+Before you can compile and run the generated API client, you need to make sure the generated source files are part of a project with the required dependencies. Your project must have a reference to the [bundle package](https://github.com/microsoft/kiota-dotnet). For more information about kiota dependencies, refer to [the dependencies documentation](../dependencies.md).
 
 Run the following commands to get the required dependencies.
 
 ```bash
-dotnet add package Microsoft.Kiota.Abstractions
-dotnet add package Microsoft.Kiota.Http.HttpClientLibrary
-dotnet add package Microsoft.Kiota.Serialization.Form
-dotnet add package Microsoft.Kiota.Serialization.Json
-dotnet add package Microsoft.Kiota.Serialization.Text
-dotnet add package Microsoft.Kiota.Serialization.Multipart
+dotnet add package Microsoft.Kiota.Bundle
 ```
 
 ## Generate the API client

OpenAPI/kiota/quickstarts/go.md

@@ -31,25 +31,12 @@ In case you're adding a Kiota client to an existing project, the following confi
 
 ## Add dependencies
 
-Before you can compile and run the generated API client, you need to make sure the generated source files are part of a project with the required dependencies. Your project must have a reference to the [abstraction package](https://github.com/microsoft/kiota-abstractions-go). Additionally, you must either use the Kiota default implementations or provide your own custom implementations of the following packages.
-
-- HTTP ([Kiota default net/http-based implementation](https://github.com/microsoft/kiota-http-go))
-- Form serialization ([Kiota default](https://github.com/microsoft/kiota-serialization-form-go))
-- JSON serialization ([Kiota default](https://github.com/microsoft/kiota-serialization-json-go))
-- Text serialization ([Kiota default](https://github.com/microsoft/kiota-serialization-text-go))
-- Multipart serialization ([Kiota default](https://github.com/microsoft/kiota-serialization-multipart-go))
-
-For this tutorial, use the default implementations.
+Before you can compile and run the generated API client, you need to make sure the generated source files are part of a project with the required dependencies. Your project must have a reference to the [bundle package](https://github.com/microsoft/kiota-bundle-go). For more information about kiota dependencies, refer to [the dependencies documentation](../dependencies.md).
 
 Run the following commands to get the required dependencies.
 
 ```bash
-go get github.com/microsoft/kiota-abstractions-go
-go get github.com/microsoft/kiota-http-go
-go get github.com/microsoft/kiota-serialization-form-go
-go get github.com/microsoft/kiota-serialization-json-go
-go get github.com/microsoft/kiota-serialization-text-go
-go get github.com/microsoft/kiota-serialization-multipart-go
+go get github.com/microsoft/kiota-bundle-go
 ```
 
 ## Generate the API client

OpenAPI/kiota/quickstarts/java.md

@@ -34,16 +34,7 @@ In case you're adding a Kiota client to an existing project, the following confi
 
 ## Add dependencies
 
-Before you can compile and run the generated API client, you need to make sure the generated source files are part of a project with the required dependencies. Your project must have a reference to the [abstraction package](https://github.com/microsoft/kiota-java). Additionally, you must either use the Kiota default implementations or provide your own custom implementations of the following packages.
-
-- HTTP ([Kiota default OkHttp-based implementation](https://github.com/microsoft/kiota-java))
-- Form serialization ([Kiota default](https://github.com/microsoft/kiota-java))
-- JSON serialization ([Kiota default](https://github.com/microsoft/kiota-java))
-- Text serialization ([Kiota default](https://github.com/microsoft/kiota-java))
-- Multipart serialization ([Kiota default](https://github.com/microsoft/kiota-java))
-- Jakarta annotations [Maven Central](https://central.sonatype.com/artifact/jakarta.annotation/jakarta.annotation-api)
-
-For this tutorial, use the default implementations.
+Before you can compile and run the generated API client, you need to make sure the generated source files are part of a project with the required dependencies. Your project must have a reference to the [bundle package](https://github.com/microsoft/kiota-java). For more information about kiota dependencies, refer to [the dependencies documentation](../dependencies.md).
 
 Edit **./app/build.gradle** to add the following dependencies.
 
@@ -63,7 +54,7 @@ This file is a minimal OpenAPI description that describes how to call the `/post
 You can then use the Kiota command line tool to generate the API client classes.
 
 ```bash
-kiota generate -l java -c PostsClient -n kiotaposts.client -d ./posts-api.yml -o ./app/src/main/java/kiotaposts/client
+kiota generate -l java -c PostsClient -n kiotaposts.client -d ./posts-api.yml -o ./app/src/main/java/kiotaposts/client --ds none -s none
 ```
 
 > [!TIP]

OpenAPI/kiota/quickstarts/typescript.md

@@ -39,25 +39,12 @@ In case you're adding a Kiota client to an existing project, the following confi
 
 ## Add dependencies
 
-Before you can compile and run the generated API client, you need to make sure the generated source files are part of a project with the required dependencies. Your project must have a reference to the [abstraction package](https://www.npmjs.com/package/@microsoft/kiota-abstractions). Additionally, you must either use the Kiota default implementations or provide your own custom implementations of the following packages.
-
-- HTTP ([Kiota default fetch-based implementation](https://www.npmjs.com/package/@microsoft/kiota-http-fetchlibrary))
-- Form serialization ([Kiota default](https://www.npmjs.com/package/@microsoft/kiota-serialization-form))
-- JSON serialization ([Kiota default](https://www.npmjs.com/package/@microsoft/kiota-serialization-json))
-- Text serialization ([Kiota default](https://www.npmjs.com/package/@microsoft/kiota-serialization-text))
-- Multipart serialization ([Kiota default](https://www.npmjs.com/package/@microsoft/kiota-serialization-multipart))
-
-For this tutorial, use the default implementations.
+Before you can compile and run the generated API client, you need to make sure the generated source files are part of a project with the required dependencies. Your project must have a reference to the [bundle package](https://github.com/microsoft/kiota-typescript). For more information about kiota dependencies, refer to [the dependencies documentation](../dependencies.md).
 
 Run the following commands to get the required dependencies.
 
 ```bash
-npm install @microsoft/kiota-abstractions
-npm install @microsoft/kiota-http-fetchlibrary
-npm install @microsoft/kiota-serialization-form
-npm install @microsoft/kiota-serialization-json
-npm install @microsoft/kiota-serialization-text
-npm install @microsoft/kiota-serialization-multipart
+npm install @microsoft/kiota-bundle
 ```
 
 ## Generate the API client

OpenAPI/kiota/toc.yml

@@ -49,6 +49,8 @@ items:
   items:
   - name: Kiota design
     href: design.md
+  - name: Managing dependencies
+    href: dependencies.md
   - name: API client experience
     href: experience.md
   - name: Abstractions