diff --git a/OpenAPI/kiota/dependencies.md b/OpenAPI/kiota/dependencies.md index 5888e7e..536dda6 100644 --- a/OpenAPI/kiota/dependencies.md +++ b/OpenAPI/kiota/dependencies.md @@ -82,7 +82,7 @@ The following table provides the list of serialization package per language. | 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 | +| Ruby | microsoft_kiota_serialization_multipart | None | | Swift | Not released | None | | TypeScript | @microsoft/kiota-serialization-multipart | None | @@ -99,7 +99,7 @@ The following table provides the list of serialization package per language. | 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 | +| Ruby | microsoft_kiota_serialization_form | None | | Swift | Not released | None | | TypeScript | @microsoft/kiota-serialization-form | None | @@ -116,7 +116,7 @@ The following table provides the list of serialization package per language. | 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 | +| Ruby | microsoft_kiota_serialization_text | None | | Swift | Not released | None | | TypeScript | @microsoft/kiota-serialization-text | None | diff --git a/OpenAPI/kiota/quickstarts/index.md b/OpenAPI/kiota/quickstarts/index.md index de564c6..e25edae 100644 --- a/OpenAPI/kiota/quickstarts/index.md +++ b/OpenAPI/kiota/quickstarts/index.md @@ -21,4 +21,5 @@ Kiota quick starts are step-by-step exercises that guide you through generating | [Java](java.md) | [microsoft/kiota-samples/get-started/quickstart/java](https://github.com/microsoft/kiota-samples/tree/main/get-started/quickstart/java) | | [PHP](php.md) | [microsoft/kiota-samples/get-started/quickstart/php](https://github.com/microsoft/kiota-samples/tree/main/get-started/quickstart/php) | | [Python](python.md) | [microsoft/kiota-samples/get-started/quickstart/python](https://github.com/microsoft/kiota-samples/tree/main/get-started/quickstart/python) | +| [Ruby](ruby.md) | [microsoft/kiota-samples/get-started/quickstart/ruby](https://github.com/microsoft/kiota-samples/tree/main/get-started/quickstart/ruby) | | [TypeScript](typescript.md) | [microsoft/kiota-samples/get-started/quickstart/typescript](https://github.com/microsoft/kiota-samples/tree/main/get-started/quickstart/typescript) | diff --git a/OpenAPI/kiota/quickstarts/ruby.md b/OpenAPI/kiota/quickstarts/ruby.md new file mode 100644 index 0000000..5bc986c --- /dev/null +++ b/OpenAPI/kiota/quickstarts/ruby.md @@ -0,0 +1,96 @@ +--- +title: Build API clients for Ruby +description: Learn how use Kiota to build API clients in Ruby. +author: baywet +ms.author: vibiret +ms.topic: quickstart +ms.date: 11/02/2026 +--- + +# Build API clients for Ruby + +In this tutorial, you build a sample app in Ruby that calls a REST API that doesn't require authentication. + +## Required tools + +- [Ruby 3.3 or newer](https://www.ruby-lang.org/en/downloads/) +- [Bundler](https://bundler.io/) + +## Create a project + +Create a directory to contain the new project, and create a new file named **Gemfile** in it. + +## 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-ruby/tree/main/components/abstractions). Additionally, you must either use the Kiota default implementations or provide your own custom implementations of the following packages. + +- HTTP ([Kiota default Faraday-based implementation](https://github.com/microsoft/kiota-ruby/tree/main/components/http)) +- JSON serialization ([Kiota default](https://github.com/microsoft/kiota-ruby/tree/main/components/serialization/json)) +- Text serialization ([Kiota default](https://github.com/microsoft/kiota-ruby/tree/main/components/serialization/text)) +- Form serialization ([Kiota default](https://github.com/microsoft/kiota-ruby/tree/main/components/serialization/form)) +- Multipart serialization ([Kiota default](https://github.com/microsoft/kiota-ruby/tree/main/components/serialization/multipart)) + +For this tutorial, use the default implementations. + +1. Edit your **Gemfile** and add the following code. + + ```ruby + source 'https://rubygems.org' + + ruby ">= 3.3.0" + + gem "microsoft_kiota_abstractions" + gem "microsoft_kiota_faraday" + gem "microsoft_kiota_serialization_json" + gem "microsoft_kiota_serialization_text" + gem "microsoft_kiota_serialization_form" + gem "microsoft_kiota_serialization_multipart" + ``` + +2. To install dependencies, run the following command. + + ```bash + bundle install + ``` + +## Generate the API client + +Kiota generates API clients from OpenAPI documents. Create a file named **posts-api.yml** and add the following. + +:::code language="yaml" source="~/code-snippets/get-started/quickstart/posts-api.yml"::: + +This file is a minimal OpenAPI description that describes how to call the `/posts` endpoint in the [JSONPlaceholder REST API](https://jsonplaceholder.typicode.com/). + +You can then use the Kiota command line tool to generate the API client classes. + +```bash +kiota generate -l ruby -c PostsClient -n KiotaPosts -d posts-api.yml -o ./client +``` + +> [!TIP] +> Add [`--exclude-backward-compatible`](../using.md#--exclude-backward-compatible---ebc) +> if you want to reduce the size of the generated client and are not concerned about +> potentially source breaking changes with future versions of Kiota when updating the client. + +## Create the client application + +Create a file in the root of the project named **main.rb** and add the following code. + +:::code language="ruby" source="~/code-snippets/get-started/quickstart/ruby/main.rb" id="ProgramSnippet"::: + +> [!NOTE] +> The [JSONPlaceholder REST API](https://jsonplaceholder.typicode.com/) doesn't require any authentication, so this sample uses the **AnonymousAuthenticationProvider**. For APIs that require authentication, use an applicable authentication provider. + +## Run the application + +To start the application, run the following command in your project directory. + +```bash +bundle exec ruby main.rb +``` + +## See also + +- [kiota-samples repository](https://github.com/microsoft/kiota-samples/tree/main/get-started/quickstart/ruby) contains the code from this guide. +- [Microsoft Graph sample using Microsoft identity platform authentication](https://github.com/microsoft/kiota-samples/tree/main/get-started/azure-auth/ruby) +- [ToDoItem Sample API](https://github.com/microsoft/kiota-samples/tree/main/sample-api) implements a sample OpenAPI in ASP.NET Core and sample clients in multiple languages. diff --git a/OpenAPI/kiota/toc.yml b/OpenAPI/kiota/toc.yml index 3a25ac0..c0c9995 100644 --- a/OpenAPI/kiota/toc.yml +++ b/OpenAPI/kiota/toc.yml @@ -23,6 +23,8 @@ items: href: quickstarts/php.md - name: Python href: quickstarts/python.md + - name: Ruby + href: quickstarts/ruby.md - name: TypeScript href: quickstarts/typescript.md - name: Tutorials diff --git a/OpenAPI/kiota/tutorials/ruby-azure.md b/OpenAPI/kiota/tutorials/ruby-azure.md index 9b602e5..56b8aa2 100644 --- a/OpenAPI/kiota/tutorials/ruby-azure.md +++ b/OpenAPI/kiota/tutorials/ruby-azure.md @@ -4,7 +4,7 @@ description: Learn how use Kiota to build API clients in Ruby to access APIs tha author: jasonjoh ms.author: jasonjoh ms.topic: tutorial -ms.date: 09/29/2026 +ms.date: 11/02/2026 --- # Build API clients for Ruby with Microsoft identity authentication @@ -22,11 +22,14 @@ Create a new file named **Gemfile** in the root directory of your project. ## 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-ruby). Additionally, you must either use the Kiota default implementations or provide your own custom implementations of the following packages. +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-ruby/tree/main/components/abstractions). Additionally, you must either use the Kiota default implementations or provide your own custom implementations of the following packages. -- Authentication ([Kiota default Azure authentication](https://github.com/microsoft/kiota-authentication-oauth-ruby)) -- HTTP ([Kiota default Faraday-based implementation](https://github.com/microsoft/kiota-http-ruby)) -- JSON serialization ([Kiota default](https://github.com/microsoft/kiota-serialization-json-ruby)) +- Authentication ([Kiota default Azure authentication](https://github.com/microsoft/kiota-ruby/tree/main/components/authentication/oauth)) +- HTTP ([Kiota default Faraday-based implementation](https://github.com/microsoft/kiota-ruby/tree/main/components/http)) +- JSON serialization ([Kiota default](https://github.com/microsoft/kiota-ruby/tree/main/components/serialization/json)) +- Text serialization ([Kiota default](https://github.com/microsoft/kiota-ruby/tree/main/components/serialization/text)) +- Form serialization ([Kiota default](https://github.com/microsoft/kiota-ruby/tree/main/components/serialization/form)) +- Multipart serialization ([Kiota default](https://github.com/microsoft/kiota-ruby/tree/main/components/serialization/multipart)) For this tutorial, use the default implementations. @@ -39,6 +42,9 @@ For this tutorial, use the default implementations. gem "microsoft_kiota_abstractions" gem "microsoft_kiota_serialization_json" + gem "microsoft_kiota_serialization_text" + gem "microsoft_kiota_serialization_form" + gem "microsoft_kiota_serialization_multipart" gem "microsoft_kiota_authentication_oauth" gem "microsoft_kiota_faraday" ``` @@ -58,15 +64,7 @@ Kiota generates API clients from OpenAPI documents. Create a file named **get-me You can then use the Kiota command line tool to generate the API client classes. ```bash -kiota generate -l ruby -d get-me.yml -n Graph -o ./client -``` - -Lastly, create a file called **graph.rb** in the `client` folder that was created by Kiota. Add the following code: - -```ruby -# frozen_string_literal: true -module Graph -end +kiota generate -l ruby -d get-me.yml -c GetUserApiClient -n GetUser -o ./client ``` ## Register an application