From 2e6378aaf52a753e54e09d3fbdba86a6d930d32a Mon Sep 17 00:00:00 2001 From: nikiforovall Date: Sun, 5 May 2024 12:36:56 +0300 Subject: [PATCH] Add docs --- docs/.vitepress/config.mts | 1 + docs/admin-rest-api/admin-api-kiota.md | 28 +++++++++++++++++++ docs/admin-rest-api/admin-api-reference.md | 2 ++ docs/admin-rest-api/admin-rest-api.md | 15 ++++++++-- docs/introduction.md | 11 ++++---- .../KeycloakRealmKiotaClientTests.cs | 4 +-- 6 files changed, 51 insertions(+), 10 deletions(-) create mode 100644 docs/admin-rest-api/admin-api-kiota.md diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index dec5fd21..c6536fb0 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -72,6 +72,7 @@ export default withMermaid({ ] }, { text: 'OpenAPI Support', link: '/admin-rest-api/admin-api-openapi' }, + { text: 'Generated Client - Kiota', link: '/admin-rest-api/admin-api-kiota' }, ] }, { diff --git a/docs/admin-rest-api/admin-api-kiota.md b/docs/admin-rest-api/admin-api-kiota.md new file mode 100644 index 00000000..9128d7e8 --- /dev/null +++ b/docs/admin-rest-api/admin-api-kiota.md @@ -0,0 +1,28 @@ +# Generated Client - Kiota + +This `KeycloakAdminApiClient` was generated using the *Kiota* library. + +> [!NOTE] +> Kiota is a powerful command line tool developed by Microsoft that simplifies the process of generating API clients for calling any OpenAPI-described API. See [OpenAPI Support](/admin-rest-api/admin-api-openapi) for more details. + +```csharp +/// +/// Adds for Keycloak Admin API. +/// +/// The IHttpClientBuilder for further configuration. +public static IHttpClientBuilder AddKeycloakAdminHttpClient( + this IServiceCollection services, + IConfiguration configuration, + Action? configureClient = default, + string keycloakClientSectionName = KeycloakAdminClientOptions.Section +); +``` + +>[!TIP] +> Kiota supports partial client generation, you can generate only the functionality you need. In this case, you can use source code of this library as an example. + +## Example + +This is an example of how to use `KeycloakAdminApiClient` together with [Access Token Management](/admin-rest-api/access-token). + +<<< @/../tests/Keycloak.AuthServices.IntegrationTests/AdminKiota/KeycloakRealmKiotaClientTests.cs#GetRealmAsyncKiota_RealmExists_Success diff --git a/docs/admin-rest-api/admin-api-reference.md b/docs/admin-rest-api/admin-api-reference.md index e3c55b26..512e52dc 100644 --- a/docs/admin-rest-api/admin-api-reference.md +++ b/docs/admin-rest-api/admin-api-reference.md @@ -11,4 +11,6 @@ The full API documentation - +/// Adds , , , HTTP clients for Keycloak Admin API. +/// +/// The IHttpClientBuilder for further configuration. public static IHttpClientBuilder AddKeycloakAdminHttpClient( this IServiceCollection services, - KeycloakAdminClientOptions keycloakAdminClientOptions, - Action? configureClient = default + IConfiguration configuration, + Action? configureClient = default, + string keycloakClientSectionName = KeycloakAdminClientOptions.Section ) ``` diff --git a/docs/introduction.md b/docs/introduction.md index 2c39dbb0..fdb7c514 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -17,8 +17,9 @@ Keycloak.AuthServices is a [family of packages](https://www.nuget.org/packages?q ## Packages -| Package | Description | -| ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [Keycloak.AuthServices.Authentication](https://www.nuget.org/packages/Keycloak.AuthServices.Authentication/2.0.0-pre-1) | As an OAuth2, OpenID Connect, and SAML compliant server, Keycloak can secure any application and service as long as the technology stack they are using supports any of these protocols. This library provides AspNetCore integration for JwtBearer and OpenIdConnect. | -| [Keycloak.AuthServices.Authorization](https://www.nuget.org/packages/Keycloak.AuthServices.Authorization/2.0.0-pre-1) | Provides Role-Based Access Control (RBAC) and integration with the Keycloak Authorization Server. | -| [Keycloak.AuthServices.Sdk](https://www.nuget.org/packages/Keycloak.AuthServices.Sdk/2.0.0-pre-1) | Provides integration with the [Keycloak Admin REST API](https://www.keycloak.org/docs-api/21.1.1/rest-api/), allowing you to manage users, roles, clients, and realms programmatically. Provides integration with the [Protection REST API](https://www.keycloak.org/docs/latest/authorization_services/index.html#_service_protection_api) - a UMA-compliant set of endpoints. | +| Package | Description | +| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Keycloak.AuthServices.Authentication](https://www.nuget.org/packages/Keycloak.AuthServices.Authentication) | As an OAuth2, OpenID Connect, and SAML compliant server, Keycloak can secure any application and service as long as the technology stack they are using supports any of these protocols. This library provides AspNetCore integration for JwtBearer and OpenIdConnect. | +| [Keycloak.AuthServices.Authorization](https://www.nuget.org/packages/Keycloak.AuthServices.Authorization) | Provides Role-Based Access Control (RBAC) and integration with the Keycloak Authorization Server. | +| [Keycloak.AuthServices.Sdk](https://www.nuget.org/packages/Keycloak.AuthServices.Sdk) | Provides integration with the [Keycloak Admin REST API](https://www.keycloak.org/docs-api/21.1.1/rest-api/), allowing you to manage users, groups, and realms programmatically. Provides integration with the [Protection REST API](https://www.keycloak.org/docs/latest/authorization_services/index.html#_service_protection_api) - a UMA-compliant set of endpoints. | +| [Keycloak.AuthServices.Sdk.Kiota](https://www.nuget.org/packages/Keycloak.AuthServices.Sdk.Kiota) | Provides integration with the [Keycloak Admin REST API](https://www.keycloak.org/docs-api/21.1.1/rest-api/). The client is generated based on Open API Spec | diff --git a/tests/Keycloak.AuthServices.IntegrationTests/AdminKiota/KeycloakRealmKiotaClientTests.cs b/tests/Keycloak.AuthServices.IntegrationTests/AdminKiota/KeycloakRealmKiotaClientTests.cs index 1defe5a7..d7076cce 100644 --- a/tests/Keycloak.AuthServices.IntegrationTests/AdminKiota/KeycloakRealmKiotaClientTests.cs +++ b/tests/Keycloak.AuthServices.IntegrationTests/AdminKiota/KeycloakRealmKiotaClientTests.cs @@ -21,7 +21,7 @@ public async Task GetRealmAsyncKiota_RealmExists_Success() var (services, configuration) = KeycloakSetup(AppSettings, testOutputHelper); var tokenClientName = "keycloak_admin_api_token"; - #region GetRealmAsync_RealmExists_Success + #region GetRealmAsyncKiota_RealmExists_Success var options = configuration.GetKeycloakOptions()!; services.AddDistributedMemoryCache(); @@ -50,7 +50,7 @@ public async Task GetRealmAsyncKiota_RealmExists_Success() realm.Should().NotBeNull(); realm!.Realm.Should().Be(realmName); - #endregion GetRealmAsync_RealmExists_Success + #endregion GetRealmAsyncKiota_RealmExists_Success } }