diff --git a/vscode/microsoft-kiota/src/kiotaInterop/lib/generateClient.ts b/vscode/microsoft-kiota/src/kiotaInterop/lib/generateClient.ts index 02e17d623f..5736670985 100644 --- a/vscode/microsoft-kiota/src/kiotaInterop/lib/generateClient.ts +++ b/vscode/microsoft-kiota/src/kiotaInterop/lib/generateClient.ts @@ -1,3 +1,26 @@ +/** + * Options for generating a client. + * + * @param {boolean} clearCache - Whether to clear the cache before generating the client. + * @param {boolean} cleanOutput - Whether to clean the output directory before generating the client. + * @param {string} clientClassName - The name of the client class to generate. + * @param {string} clientNamespaceName - The namespace name for the generated client. + * @param {string[]} deserializers - The list of deserializers to use. + * @param {string[]} disabledValidationRules - The list of validation rules to disable. + * @param {boolean} excludeBackwardCompatible - Whether to exclude backward-compatible changes. + * @param {string[]} excludePatterns - The list of patterns to exclude from generation. + * @param {boolean} includeAdditionalData - Whether to include additional data in the generated client. + * @param {string[]} includePatterns - The list of patterns to include in generation. + * @param {KiotaGenerationLanguage} language - The programming language for the generated client. + * @param {string} openAPIFilePath - The file path to the OpenAPI specification. + * @param {string} outputPath - The output path for the generated client. + * @param {string[]} serializers - The list of serializers to use. + * @param {string[]} structuredMimeTypes - The list of structured MIME types to support. + * @param {boolean} usesBackingStore - Whether the generated client uses a backing store. + * @param {ConsumerOperation} operation - The consumer operation to perform. + * @param {string} workingDirectory - The working directory for the generation process. + * + */ import * as rpc from "vscode-jsonrpc/node"; import { checkForSuccess, ConsumerOperation, GenerationConfiguration, KiotaLogEntry } from ".."; @@ -26,6 +49,34 @@ interface ClientGenerationOptions { workingDirectory: string; } +/** + * Generates a client based on the provided client generation options. + * + * @param {ClientGenerationOptions} clientGenerationOptions - The options for generating the client. + * * Options for generating a client. + * + * @param {boolean} clientGenerationOptions.clearCache - Whether to clear the cache before generating the client. + * @param {boolean} clientGenerationOptions.cleanOutput - Whether to clean the output directory before generating the client. + * @param {string} clientGenerationOptions.clientClassName - The name of the client class to generate. + * @param {string} clientGenerationOptions.clientNamespaceName - The namespace name for the generated client. + * @param {string[]} clientGenerationOptions.deserializers - The list of deserializers to use. + * @param {string[]} clientGenerationOptions.disabledValidationRules - The list of validation rules to disable. + * @param {boolean} clientGenerationOptions.excludeBackwardCompatible - Whether to exclude backward-compatible changes. + * @param {string[]} clientGenerationOptions.excludePatterns - The list of patterns to exclude from generation. + * @param {boolean} clientGenerationOptions.includeAdditionalData - Whether to include additional data in the generated client. + * @param {string[]} clientGenerationOptions.includePatterns - The list of patterns to include in generation. + * @param {KiotaGenerationLanguage} clientGenerationOptions.language - The programming language for the generated client. + * @param {string} clientGenerationOptions.openAPIFilePath - The file path to the OpenAPI specification. + * @param {string} clientGenerationOptions.outputPath - The output path for the generated client. + * @param {string[]} clientGenerationOptions.serializers - The list of serializers to use. + * @param {string[]} clientGenerationOptions.structuredMimeTypes - The list of structured MIME types to support. + * @param {boolean} clientGenerationOptions.usesBackingStore - Whether the generated client uses a backing store. + * @param {ConsumerOperation} clientGenerationOptions.operation - The consumer operation to perform. + * @param {string} clientGenerationOptions.workingDirectory - The working directory for the generation process. + + * @returns {Promise} A promise that resolves to a KiotaResult if successful, or undefined if not. + * @throws {Error} If an error occurs during the client generation process. + */ export async function generateClient(clientGenerationOptions: ClientGenerationOptions): Promise { const result = await connectToKiota(async (connection) => { const request = new rpc.RequestType1( diff --git a/vscode/microsoft-kiota/src/kiotaInterop/lib/generatePlugin.ts b/vscode/microsoft-kiota/src/kiotaInterop/lib/generatePlugin.ts index a91c06349b..f15443e326 100644 --- a/vscode/microsoft-kiota/src/kiotaInterop/lib/generatePlugin.ts +++ b/vscode/microsoft-kiota/src/kiotaInterop/lib/generatePlugin.ts @@ -21,6 +21,29 @@ interface PluginGenerationOptions { workingDirectory: string; } +/** + * Generates a plugin based on the provided options. + * + * @param {PluginGenerationOptions} pluginGenerationOptions - The options for generating the plugin. + * @param {string} pluginGenerationOptions.openAPIFilePath - The file path to the OpenAPI specification. + * @param {string} pluginGenerationOptions.outputPath - The output path where the generated plugin will be saved. + * @param {KiotaPluginType[]} pluginGenerationOptions.pluginTypes - The types of plugins to generate. + * @param {string[]} pluginGenerationOptions.includePatterns - The patterns to include in the generation process. + * @param {string[]} pluginGenerationOptions.excludePatterns - The patterns to exclude from the generation process. + * @param {string} pluginGenerationOptions.clientClassName - The name of the client class to generate. + * @param {boolean} pluginGenerationOptions.clearCache - Whether to clear the cache before generation. + * @param {boolean} pluginGenerationOptions.cleanOutput - Whether to clean the output directory before generation. + * @param {string[]} pluginGenerationOptions.disabledValidationRules - The validation rules to disable during generation. + * @param {ConsumerOperation} pluginGenerationOptions.operation - The operation to perform during generation. + * @param {PluginAuthType | null} [pluginGenerationOptions.pluginAuthType] - The authentication type for the plugin, if any. + * @param {string} [pluginGenerationOptions.pluginAuthRefid] - The reference ID for the plugin authentication, if any. + * @param {string} pluginGenerationOptions.workingDirectory - The working directory for the generation process. + * @returns {Promise} A promise that resolves to a KiotaResult if successful, or undefined if not. + * @throws {Error} If an error occurs during the generation process. + * + * The function connects to Kiota and sends a request to generate a plugin using the provided options. + * It handles the response and checks for success, returning the result or throwing an error if one occurs. + */ export async function generatePlugin(pluginGenerationOptions: PluginGenerationOptions ): Promise { const result = await connectToKiota(async (connection) => { diff --git a/vscode/microsoft-kiota/src/kiotaInterop/lib/getKiotaTree.ts b/vscode/microsoft-kiota/src/kiotaInterop/lib/getKiotaTree.ts index 407d9f1213..b68451c95d 100644 --- a/vscode/microsoft-kiota/src/kiotaInterop/lib/getKiotaTree.ts +++ b/vscode/microsoft-kiota/src/kiotaInterop/lib/getKiotaTree.ts @@ -10,6 +10,17 @@ interface KiotaResultOptions { clearCache: boolean; } +/** + * Shows the Kiota result based on the provided options. + * + * @param {KiotaResultOptions} options - The options to configure the Kiota result. + * @param {string[]} options.includeFilters - Filters to include in the result. + * @param {string} options.descriptionPath - The path to the description file. + * @param {string[]} options.excludeFilters - Filters to exclude from the result. + * @param {boolean} options.clearCache - Whether to clear the cache before showing the result. + * @returns {Promise} A promise that resolves to the Kiota show result or undefined if an error occurs. + * @throws {Error} Throws an error if the result is an instance of Error. + */ export async function getKiotaTree({ includeFilters, descriptionPath, excludeFilters, clearCache }: KiotaResultOptions): Promise { const result = await connectToKiota(async (connection) => { const request = new rpc.RequestType('Show'); diff --git a/vscode/microsoft-kiota/src/kiotaInterop/lib/getKiotaVersion.ts b/vscode/microsoft-kiota/src/kiotaInterop/lib/getKiotaVersion.ts index b34118ed8c..1c578af2aa 100644 --- a/vscode/microsoft-kiota/src/kiotaInterop/lib/getKiotaVersion.ts +++ b/vscode/microsoft-kiota/src/kiotaInterop/lib/getKiotaVersion.ts @@ -2,6 +2,12 @@ import * as rpc from "vscode-jsonrpc/node"; import connectToKiota from '../connect'; +/** + * Retrieves the version of Kiota by connecting to the Kiota service. + * + * @returns {Promise} A promise that resolves to the Kiota version string if available, otherwise undefined. + * @throws {Error} If an error occurs while connecting to the Kiota service or retrieving the version. + */ export async function getKiotaVersion(): Promise { const result = await connectToKiota(async (connection) => { diff --git a/vscode/microsoft-kiota/src/kiotaInterop/lib/getManifestDetails.ts b/vscode/microsoft-kiota/src/kiotaInterop/lib/getManifestDetails.ts index d1fbb82e44..8948573202 100644 --- a/vscode/microsoft-kiota/src/kiotaInterop/lib/getManifestDetails.ts +++ b/vscode/microsoft-kiota/src/kiotaInterop/lib/getManifestDetails.ts @@ -9,6 +9,16 @@ interface ManifestOptions { apiIdentifier?: string; } +/** + * Retrieves the manifest details for a given API. + * + * @param {ManifestOptions} options - The options for retrieving the manifest details. + * @param {string} options.manifestPath - The path to the manifest file. + * @param {boolean} options.clearCache - Whether to clear the cache before retrieving the manifest details. + * @param {string} [options.apiIdentifier] - The identifier of the API. + * @returns {Promise} A promise that resolves to the manifest details or undefined if not found. + * @throws {Error} Throws an error if the request fails. + */ export async function getManifestDetails({ manifestPath, clearCache, apiIdentifier }: ManifestOptions): Promise { const result = await connectToKiota(async (connection) => { const request = new rpc.RequestType('GetManifestDetails'); diff --git a/vscode/microsoft-kiota/src/kiotaInterop/lib/languageInformation.ts b/vscode/microsoft-kiota/src/kiotaInterop/lib/languageInformation.ts index 793e5aca6a..50380ae0f4 100644 --- a/vscode/microsoft-kiota/src/kiotaInterop/lib/languageInformation.ts +++ b/vscode/microsoft-kiota/src/kiotaInterop/lib/languageInformation.ts @@ -7,6 +7,16 @@ interface LanguageInformationConfiguration { descriptionUrl: string; clearCache: boolean; } +/** + * Retrieves language information by connecting to Kiota. + * + * This function establishes a connection to Kiota and sends a request to retrieve + * language information. If the request is successful, it returns the language information. + * If an error occurs during the request, the error is thrown. + * + * @returns {Promise} A promise that resolves to the language information or undefined if an error occurs. + * @throws {Error} Throws an error if the request fails. + */ export async function getLanguageInformationInternal(): Promise { const result = await connectToKiota(async (connection) => { const request = new rpc.RequestType0( @@ -24,6 +34,17 @@ export async function getLanguageInformationInternal(): Promise} A promise that resolves to the language information or undefined if an error occurs. + * + * @throws {Error} Throws an error if the request fails. + */ export async function getLanguageInformationForDescription({ descriptionUrl, clearCache }: LanguageInformationConfiguration): Promise { const result = await connectToKiota(async (connection) => { diff --git a/vscode/microsoft-kiota/src/kiotaInterop/lib/migrateFromLockFile.ts b/vscode/microsoft-kiota/src/kiotaInterop/lib/migrateFromLockFile.ts index 2fc60d1912..e383da97db 100644 --- a/vscode/microsoft-kiota/src/kiotaInterop/lib/migrateFromLockFile.ts +++ b/vscode/microsoft-kiota/src/kiotaInterop/lib/migrateFromLockFile.ts @@ -3,6 +3,17 @@ import * as rpc from "vscode-jsonrpc/node"; import { KiotaLogEntry } from ".."; import connectToKiota from "../connect"; +/** + * Migrates data from a lock file located in the specified directory. + * + * This function connects to the Kiota service and sends a request to migrate data from the lock file. + * If the migration is successful, it returns an array of `KiotaLogEntry` objects. + * If an error occurs during the migration, the error is thrown. + * + * @param {string} lockFileDirectory - The directory where the lock file is located. + * @returns {Promise} A promise that resolves to an array of `KiotaLogEntry` objects if the migration is successful, or `undefined` if no data is migrated. + * @throws {Error} If an error occurs during the migration process. + */ export async function migrateFromLockFile(lockFileDirectory: string): Promise { const result = await connectToKiota(async (connection) => { const request = new rpc.RequestType1( diff --git a/vscode/microsoft-kiota/src/kiotaInterop/lib/removeItem.ts b/vscode/microsoft-kiota/src/kiotaInterop/lib/removeItem.ts index 168dfd18f8..0410e046aa 100644 --- a/vscode/microsoft-kiota/src/kiotaInterop/lib/removeItem.ts +++ b/vscode/microsoft-kiota/src/kiotaInterop/lib/removeItem.ts @@ -16,6 +16,16 @@ interface RemoveClientConfiguration extends RemoveItemConfiguration { clientName: string; } +/** + * Removes a plugin from the Kiota environment. + * + * @param {RemovePluginConfiguration} config - The configuration for removing the plugin. + * @param {string} config.pluginName - The name of the plugin to remove. + * @param {boolean} config.cleanOutput - Whether to clean the output directory after removal. + * @param {string} config.workingDirectory - The working directory where the operation should be performed. + * @returns {Promise} A promise that resolves to a KiotaResult if the operation is successful, or undefined if no result is returned. + * @throws {Error} Throws an error if the operation fails. + */ export async function removePlugin({ pluginName, cleanOutput, workingDirectory }: RemovePluginConfiguration): Promise { const result = await connectToKiota(async (connection) => { const request = new rpc.RequestType2( @@ -42,10 +52,16 @@ export async function removePlugin({ pluginName, cleanOutput, workingDirectory } return undefined; }; - - - - +/** + * Removes a client using the provided configuration. + * + * @param {RemoveClientConfiguration} config - The configuration for removing the client. + * @param {string} config.clientName - The name of the client to be removed. + * @param {boolean} config.cleanOutput - A flag indicating whether to clean the output. + * @param {string} config.workingDirectory - The working directory for the operation. + * @returns {Promise} A promise that resolves to a KiotaResult if the client was removed successfully, or undefined if no result is returned. + * @throws {Error} Throws an error if the result is an instance of Error. + */ export async function removeClient({ clientName, cleanOutput, workingDirectory }: RemoveClientConfiguration): Promise { const result = await connectToKiota(async (connection) => { const request = new rpc.RequestType2( diff --git a/vscode/microsoft-kiota/src/kiotaInterop/lib/searchDescription.ts b/vscode/microsoft-kiota/src/kiotaInterop/lib/searchDescription.ts index 54e86546bb..451c33910f 100644 --- a/vscode/microsoft-kiota/src/kiotaInterop/lib/searchDescription.ts +++ b/vscode/microsoft-kiota/src/kiotaInterop/lib/searchDescription.ts @@ -8,6 +8,15 @@ interface SearchConfiguration { clearCache: boolean; } +/** + * Searches for a description based on the provided search term and cache settings. + * + * @param {SearchConfiguration} config - The search configuration object. + * @param {string} config.searchTerm - The term to search for. + * @param {boolean} config.clearCache - Whether to clear the cache before searching. + * @returns {Promise | undefined>} A promise that resolves to a record of search results or undefined if no results are found. + * @throws {Error} Throws an error if the search operation fails. + */ export async function searchDescription({ searchTerm, clearCache }: SearchConfiguration): Promise | undefined> { const result = await connectToKiota(async (connection) => { const request = new rpc.RequestType2( diff --git a/vscode/microsoft-kiota/src/kiotaInterop/lib/updateClients.ts b/vscode/microsoft-kiota/src/kiotaInterop/lib/updateClients.ts index 08fd8d9a01..291abc64ca 100644 --- a/vscode/microsoft-kiota/src/kiotaInterop/lib/updateClients.ts +++ b/vscode/microsoft-kiota/src/kiotaInterop/lib/updateClients.ts @@ -9,6 +9,18 @@ interface UpdateClientsConfiguration { workspacePath: string; } +/** + * Updates the clients by connecting to Kiota and sending a request to update. + * + * @param {UpdateClientsConfiguration} config - The configuration object containing the following properties: + * @param {boolean} config.cleanOutput - Whether to clean the output directory before updating. + * @param {boolean} config.clearCache - Whether to clear the cache before updating. + * @param {string} config.workspacePath - The path to the workspace where the clients are located. + * + * @returns {Promise} A promise that resolves to an array of Kiota log entries if the update is successful, or undefined if there is an error. + * + * @throws {Error} Throws an error if the result of the update is an instance of Error. + */ export async function updateClients({ cleanOutput, clearCache, workspacePath }: UpdateClientsConfiguration): Promise { const result = await connectToKiota(async (connection) => { const request = new rpc.RequestType3( diff --git a/vscode/microsoft-kiota/src/kiotaInterop/readme.md b/vscode/microsoft-kiota/src/kiotaInterop/readme.md new file mode 100644 index 0000000000..38357913cc --- /dev/null +++ b/vscode/microsoft-kiota/src/kiotaInterop/readme.md @@ -0,0 +1,59 @@ +# Kiota Interop Library + +This library provides various functions to interact with Kiota, a client generator for HTTP REST APIs described by OpenAPI. + +## Installation +Provide instructions on how to install the project. + +```bash +npm install kiota-Interop +``` + +## Usage + +### [`getKiotaTree`](/kiotaInterop./lib/getKiotaTree.ts ) +Returns a tree of the open api description. + +### [`generateClient`](./lib/generateClient.ts ) + +Generates a client based on the provided client generation options. + +### [`generatePlugin`](./lib/generatePlugin.ts ) + +The function connects to Kiota and sends a request to generate a plugin using the provided options. +It handles the response and checks for success, returning the result or throwing an error if one occurs. + +### [`getKiotaVersion`](./lib/getKiotaVersion.ts ) + +Retrieves the version of Kiota by connecting to the Kiota service. + + +### [`getManifestDetails`](./lib/getManifestDetails.ts ) + +Retrieves the manifest details for a given API. + +### [`getLanguageInformationInternal`](./lib/languageInformation.ts ) + +Retrieves language information by connecting to Kiota + +### [`getLanguageInformationForDescription`](./lib/languageInformation.ts ) + +Retrieves language information based on the provided description URL. + +### [`migrateFromLockFile`](./lib/migrateFromLockFile.ts ) + +Migrates data from a lock file located in the specified directory. + +### [`removePlugin`](./lib/removeItem.ts ) + +Removes a plugin from the Kiota environment. + +### [`removeClient`](./lib/removeItem.ts ) +Removes a client using the provided configuration. + +### [`searchDescription`](./lib/searchDescription.ts ) +Searches for a description based on the provided search term and cache settings. + +### [`updateClients`](./lib/updateClients.ts ) +Updates the clients in the Kiota environment. +