Skip to content

Commit 5e6fdf4

Browse files
baywetbaywet
authored
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]>
1 parent 425e67d commit 5e6fdf4

File tree

15 files changed

+293
-174
lines changed

15 files changed

+293
-174
lines changed

‎.vscode/settings.json

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,5 +2,8 @@
22
"cSpell.spellCheckOnlyWorkspaceFiles": true,
33
"markdownlint.ignore": [
44
"LICENSE-CODE"
5-
]
5+
],
6+
"cSpell.words": [
7+
"kiota"
8+
]
69
}

‎OpenAPI/kiota/dependencies.md

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
---
2+
title: Managing dependencies of Kiota API clients
3+
description: Learn what different dependencies bring to your project and how to manage them.
4+
author: baywet
5+
ms.author: vibiret
6+
ms.topic: conceptual
7+
date: 03/21/2023
8+
---
9+
10+
# Managing dependencies of Kiota API clients
11+
12+
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.
13+
14+
## Guidance
15+
16+
### Generated client and dependencies versions alignment
17+
18+
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.
19+
20+
[More information about the info command](./using.md#language-information)
21+
22+
### Dependencies selection
23+
24+
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.
25+
26+
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.
27+
28+
Additionally, your application might need to reference an [authentication](#authentication) package depending on the target API.
29+
30+
## Abstractions
31+
32+
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.
33+
34+
[More information about the abstractions package](./abstractions.md)
35+
36+
The following table provides the list of abstractions package per language.
37+
38+
| Language | Package Name |
39+
| -------- | ------------ |
40+
| C# | Microsoft.Kiota.Abstractions |
41+
| CLI | Microsoft.Kiota.Abstractions |
42+
| Go | github.com/microsoft/kiota-abstractions-go |
43+
| Java | com.microsoft.kiota:microsoft-kiota-abstractions |
44+
| PHP | microsoft/kiota-abstractions |
45+
| Python | microsoft-kiota-abstractions |
46+
| Ruby | microsoft_kiota_abstractions |
47+
| Swift | Not released |
48+
| TypeScript | @microsoft/kiota-abstractions |
49+
50+
## Serialization
51+
52+
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.
53+
54+
[More information about the serialization packages](./serialization.md)
55+
56+
### JSON
57+
58+
Media type: application/json
59+
60+
The following table provides the list of serialization package per language.
61+
62+
| Language | Package Name | Relies on |
63+
| -------- | ------------ | --------- |
64+
| C# | Microsoft.Kiota.Serialization.Json | System.Text.Json |
65+
| CLI | Microsoft.Kiota.Serialization.Json | System.Text.Json |
66+
| Go | github.com/microsoft/kiota-serialization-json-go | None |
67+
| Java | com.microsoft.kiota:microsoft-kiota-serialization-json | Gson |
68+
| PHP | microsoft/kiota-serialization-json | None |
69+
| Python | microsoft-kiota-serialization-json | None |
70+
| Ruby | microsoft_kiota_serialization_json | None |
71+
| Swift | Not released | None |
72+
| TypeScript | @microsoft/kiota-serialization-json | None |
73+
74+
### Multipart
75+
76+
Media type: multipart/form-data
77+
78+
The following table provides the list of serialization package per language.
79+
80+
| Language | Package Name | Relies on |
81+
| -------- | ------------ | --------- |
82+
| C# | Microsoft.Kiota.Serialization.Multipart | None |
83+
| CLI | Microsoft.Kiota.Serialization.Multipart | None |
84+
| Go | github.com/microsoft/kiota-serialization-multipart-go | None |
85+
| Java | com.microsoft.kiota:microsoft-kiota-serialization-multipart | None |
86+
| PHP | microsoft/kiota-serialization-multipart | None |
87+
| Python | microsoft-kiota-serialization-multipart | None |
88+
| Ruby | Not released | None |
89+
| Swift | Not released | None |
90+
| TypeScript | @microsoft/kiota-serialization-multipart | None |
91+
92+
### Form
93+
94+
Media type: application/x-www-form-urlencoded
95+
96+
The following table provides the list of serialization package per language.
97+
98+
| Language | Package Name | Relies on |
99+
| -------- | ------------ | --------- |
100+
| C# | Microsoft.Kiota.Serialization.Form | None |
101+
| CLI | Microsoft.Kiota.Serialization.Form | None |
102+
| Go | github.com/microsoft/kiota-serialization-form-go | None |
103+
| Java | com.microsoft.kiota:microsoft-kiota-serialization-form | None |
104+
| PHP | microsoft/kiota-serialization-form | None |
105+
| Python | microsoft-kiota-serialization-form | None |
106+
| Ruby | Not Released | None |
107+
| Swift | Not released | None |
108+
| TypeScript | @microsoft/kiota-serialization-form | None |
109+
110+
### Text
111+
112+
Media type: text/plain
113+
114+
The following table provides the list of serialization package per language.
115+
116+
| Language | Package Name | Relies on |
117+
| -------- | ------------ | --------- |
118+
| C# | Microsoft.Kiota.Serialization.Text | None |
119+
| CLI | Microsoft.Kiota.Serialization.Text | None |
120+
| Go | github.com/microsoft/kiota-serialization-text-go | None |
121+
| Java | com.microsoft.kiota:microsoft-kiota-serialization-text | None |
122+
| PHP | microsoft/kiota-serialization-text | None |
123+
| Python | microsoft-kiota-serialization-text | None |
124+
| Ruby | Not Released | None |
125+
| Swift | Not released | None |
126+
| TypeScript | @microsoft/kiota-serialization-text | None |
127+
128+
## Http
129+
130+
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.
131+
132+
[More information about the HTTP package](./middleware.md).
133+
134+
The following table provides the list of HTTP package per language.
135+
136+
| Language | Package Name | Relies on |
137+
| -------- | ------------ | --------- |
138+
| C# | Microsoft.Kiota.Http.HttpClientLibrary | System.Net.Http |
139+
| CLI | Microsoft.Kiota.Http.HttpClientLibrary | System.Net.Http |
140+
| Go | github.com/microsoft/kiota-http-go | net/http |
141+
| Java | com.microsoft.kiota:microsoft-kiota-http-okHttp | None |
142+
| PHP | microsoft/kiota-http-guzzle | None |
143+
| Python | microsoft-kiota-http | None |
144+
| Ruby | microsoft_kiota_faraday | None |
145+
| Swift | Not released | None |
146+
| TypeScript | @microsoft/kiota-http-fetchlibrary | None |
147+
148+
## Authentication
149+
150+
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.
151+
152+
[More information about the authentication package](./authentication.md)
153+
154+
### Azure Identity
155+
156+
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.
157+
158+
The following table provides the list of authentication package per language.
159+
160+
| Language | Package Name | Relies on |
161+
| -------- | ------------ | --------- |
162+
| C# | Microsoft.Kiota.Authentication.Azure | Azure.Identity |
163+
| CLI | Microsoft.Kiota.Authentication.Azure | Azure.Identity |
164+
| Go | github.com/microsoft/kiota-authentication-azure-go | github.com/Azure/azure-sdk-for-go/sdk/azidentity |
165+
| Java | com.microsoft.kiota:microsoft-kiota-authentication-azure | com.azure:azure-identity |
166+
| PHP | microsoft/kiota-authentication-phpleague | phpleague |
167+
| Python | microsoft-kiota-authentication-azure | azure-identity |
168+
| Ruby | microsoft_kiota_authentication_oauth | oauth |
169+
| Swift | Not released | None |
170+
| TypeScript | @microsoft/kiota-authentication-azure | @azure/identity |
171+
172+
## Additional
173+
174+
Additional dependencies are required at build time and/or runtime.
175+
176+
The following table provides the list of additional package per language.
177+
178+
| Language | Package Name | Type |
179+
| -------- | ------------ | ---- |
180+
| C# | None | |
181+
| CLI | Microsoft.Kiota.CLI.Commons, System.CommandLine | Build and runtime |
182+
| Go | None | |
183+
| Java | jakarta.annotation:jakarta.annotation-api:2.0.0 | Build |
184+
| PHP | None | |
185+
| Python | None | |
186+
| Ruby | None | |
187+
| Swift | None | |
188+
| TypeScript | None | |
189+
190+
## Bundle
191+
192+
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.
193+
194+
The following table provides the list of bundle package per language.
195+
196+
| Language | Package Name |
197+
| -------- | ------------ |
198+
| C# | Microsoft.Kiota.Bundle |
199+
| CLI | Microsoft.Kiota.Bundle |
200+
| Go | github.com/microsoft/kiota-bundle-go |
201+
| Java | com.microsoft.kiota:microsoft-kiota-bundle |
202+
| PHP | Not available |
203+
| Python | Not available |
204+
| Ruby | Not available |
205+
| Swift | Not available |
206+
| TypeScript | @microsoft/kiota-bundle |

‎OpenAPI/kiota/quickstarts/cli.md

Lines changed: 2 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -38,26 +38,15 @@ In case you're adding a Kiota client to an existing project, the following confi
3838

3939
## Add dependencies
4040

41-
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.
42-
43-
- HTTP ([Kiota default HttpClient-based implementation](https://github.com/microsoft/kiota-http-dotnet))
44-
- Form serialization ([Kiota default](https://github.com/microsoft/kiota-serialization-form-dotnet))
45-
- JSON serialization ([Kiota default](https://github.com/microsoft/kiota-serialization-json-dotnet))
46-
- Text serialization ([Kiota default](https://github.com/microsoft/kiota-serialization-text-dotnet))
47-
- Multipart serialization ([Kiota default](https://github.com/microsoft/kiota-serialization-multipart-dotnet))
41+
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).
4842

4943
For this tutorial, use the default implementations.
5044

5145
Run the following commands to get the required dependencies.
5246

5347
```bash
54-
dotnet add package Microsoft.Kiota.Abstractions
48+
dotnet add package Microsoft.Kiota.Bundle
5549
dotnet add package Microsoft.Kiota.Cli.Commons --prerelease
56-
dotnet add package Microsoft.Kiota.Http.HttpClientLibrary
57-
dotnet add package Microsoft.Kiota.Serialization.Form
58-
dotnet add package Microsoft.Kiota.Serialization.Json
59-
dotnet add package Microsoft.Kiota.Serialization.Text
60-
dotnet add package Microsoft.Kiota.Serialization.Multipart
6150
```
6251

6352
## Generate the API client

‎OpenAPI/kiota/quickstarts/dotnet.md

Lines changed: 2 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -37,25 +37,12 @@ The following configuration is recommended:
3737

3838
## Add dependencies
3939

40-
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.
41-
42-
- HTTP ([Kiota default HttpClient-based implementation](https://github.com/microsoft/kiota-http-dotnet))
43-
- Form serialization ([Kiota default](https://github.com/microsoft/kiota-serialization-form-dotnet))
44-
- JSON serialization ([Kiota default](https://github.com/microsoft/kiota-serialization-json-dotnet))
45-
- Text serialization ([Kiota default](https://github.com/microsoft/kiota-serialization-text-dotnet))
46-
- Multipart serialization ([Kiota default](https://github.com/microsoft/kiota-serialization-multipart-dotnet))
47-
48-
For this tutorial, use the default implementations.
40+
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).
4941

5042
Run the following commands to get the required dependencies.
5143

5244
```bash
53-
dotnet add package Microsoft.Kiota.Abstractions
54-
dotnet add package Microsoft.Kiota.Http.HttpClientLibrary
55-
dotnet add package Microsoft.Kiota.Serialization.Form
56-
dotnet add package Microsoft.Kiota.Serialization.Json
57-
dotnet add package Microsoft.Kiota.Serialization.Text
58-
dotnet add package Microsoft.Kiota.Serialization.Multipart
45+
dotnet add package Microsoft.Kiota.Bundle
5946
```
6047

6148
## Generate the API client

‎OpenAPI/kiota/quickstarts/go.md

Lines changed: 2 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -31,25 +31,12 @@ In case you're adding a Kiota client to an existing project, the following confi
3131

3232
## Add dependencies
3333

34-
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.
35-
36-
- HTTP ([Kiota default net/http-based implementation](https://github.com/microsoft/kiota-http-go))
37-
- Form serialization ([Kiota default](https://github.com/microsoft/kiota-serialization-form-go))
38-
- JSON serialization ([Kiota default](https://github.com/microsoft/kiota-serialization-json-go))
39-
- Text serialization ([Kiota default](https://github.com/microsoft/kiota-serialization-text-go))
40-
- Multipart serialization ([Kiota default](https://github.com/microsoft/kiota-serialization-multipart-go))
41-
42-
For this tutorial, use the default implementations.
34+
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).
4335

4436
Run the following commands to get the required dependencies.
4537

4638
```bash
47-
go get github.com/microsoft/kiota-abstractions-go
48-
go get github.com/microsoft/kiota-http-go
49-
go get github.com/microsoft/kiota-serialization-form-go
50-
go get github.com/microsoft/kiota-serialization-json-go
51-
go get github.com/microsoft/kiota-serialization-text-go
52-
go get github.com/microsoft/kiota-serialization-multipart-go
39+
go get github.com/microsoft/kiota-bundle-go
5340
```
5441

5542
## Generate the API client

‎OpenAPI/kiota/quickstarts/java.md

Lines changed: 2 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -34,16 +34,7 @@ In case you're adding a Kiota client to an existing project, the following confi
3434

3535
## Add dependencies
3636

37-
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.
38-
39-
- HTTP ([Kiota default OkHttp-based implementation](https://github.com/microsoft/kiota-java))
40-
- Form serialization ([Kiota default](https://github.com/microsoft/kiota-java))
41-
- JSON serialization ([Kiota default](https://github.com/microsoft/kiota-java))
42-
- Text serialization ([Kiota default](https://github.com/microsoft/kiota-java))
43-
- Multipart serialization ([Kiota default](https://github.com/microsoft/kiota-java))
44-
- Jakarta annotations [Maven Central](https://central.sonatype.com/artifact/jakarta.annotation/jakarta.annotation-api)
45-
46-
For this tutorial, use the default implementations.
37+
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).
4738

4839
Edit **./app/build.gradle** to add the following dependencies.
4940

@@ -63,7 +54,7 @@ This file is a minimal OpenAPI description that describes how to call the `/post
6354
You can then use the Kiota command line tool to generate the API client classes.
6455

6556
```bash
66-
kiota generate -l java -c PostsClient -n kiotaposts.client -d ./posts-api.yml -o ./app/src/main/java/kiotaposts/client
57+
kiota generate -l java -c PostsClient -n kiotaposts.client -d ./posts-api.yml -o ./app/src/main/java/kiotaposts/client --ds none -s none
6758
```
6859

6960
> [!TIP]

‎OpenAPI/kiota/quickstarts/typescript.md

Lines changed: 2 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -39,25 +39,12 @@ In case you're adding a Kiota client to an existing project, the following confi
3939

4040
## Add dependencies
4141

42-
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.
43-
44-
- HTTP ([Kiota default fetch-based implementation](https://www.npmjs.com/package/@microsoft/kiota-http-fetchlibrary))
45-
- Form serialization ([Kiota default](https://www.npmjs.com/package/@microsoft/kiota-serialization-form))
46-
- JSON serialization ([Kiota default](https://www.npmjs.com/package/@microsoft/kiota-serialization-json))
47-
- Text serialization ([Kiota default](https://www.npmjs.com/package/@microsoft/kiota-serialization-text))
48-
- Multipart serialization ([Kiota default](https://www.npmjs.com/package/@microsoft/kiota-serialization-multipart))
49-
50-
For this tutorial, use the default implementations.
42+
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).
5143

5244
Run the following commands to get the required dependencies.
5345

5446
```bash
55-
npm install @microsoft/kiota-abstractions
56-
npm install @microsoft/kiota-http-fetchlibrary
57-
npm install @microsoft/kiota-serialization-form
58-
npm install @microsoft/kiota-serialization-json
59-
npm install @microsoft/kiota-serialization-text
60-
npm install @microsoft/kiota-serialization-multipart
47+
npm install @microsoft/kiota-bundle
6148
```
6249

6350
## Generate the API client

‎OpenAPI/kiota/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,8 @@ items:
4949
items:
5050
- name: Kiota design
5151
href: design.md
52+
- name: Managing dependencies
53+
href: dependencies.md
5254
- name: API client experience
5355
href: experience.md
5456
- name: Abstractions

0 commit comments

Comments
 (0)