Introducing kiota.config spec

specs/cli/client-add.md

@@ -0,0 +1,169 @@
+# kiota client add
+
+## Description 
+
+`kiota client add` allows a developer to add a new API client to the `kiota-config.json` file. If no `kiota-config.json` file is found, a new `kiota-config.json` file would be created. The command will add a new entry to the `clients` section of the `kiota-config.json` file. Once this is done, a local copy of the OpenAPI description is generated and kepts in the .
+
+When executing, a new API entry will be added and will use the `--client-name` parameter as the key for the map. When loading the OpenAPI description, it will generate a hash of the description to enable change detection of the description and save it as part of the `descriptionHash` property. It will also store the location of the description in the `descriptionLocation` property. If `--include-path` or `--exclude-path` are provided, they will be stored in the `includePatterns` and `excludePatterns` properties respectively.
+
+Every time an API client is added, a copy of the OpenAPI description file will be stored in the `./.kiota` folder. The file will be named using the hash of the description. This will allow the CLI to detect changes in the description and avoid downloading the description again if it hasn't changed. 
+
+At the same time, an [API Manifest](https://www.ietf.org/archive/id/draft-miller-api-manifest-01.html#section-2.5-3) file will be generated (if non existing) or edited (if already existing) to represent the surface of the API being used. This file will be named `apimanifest.json` and will be stored in the `./.kiota` folder. This file will be used to generate the code files.
+
+Once the `kiota-config.json` file is generated, the OpenAPI description file is saved locally and the API Manifest is available, the code generation will be executed.
+
+## Parameters
+
+| Parameters | Required | Example | Description |
+| -- | -- | -- | -- |
+| `--config-location \| --cl` | No | ./.kiota/kiota-config.json | A location where to find or create the `kiota-config.json` file. When not specified it will find an ancestor `kiota-config.json` file and if not found, will use `./.kiota/kiota-config.json`. |
+| `--client-name \| --cn` | Yes | graphDelegated | Name of the client. Unique within the parent API. If not provided, defaults to --class-name or its default. |
+| `--openapi \| -d` | Yes | https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/master/openapi/v1.0/openapi.yaml | The location of the OpenAPI description in JSON or YAML format to use to generate the SDK. Accepts a URL or a local path. |
+| `--include-path \| -i` | No | /me/chats#GET | A glob pattern to include paths from generation. Accepts multiple values. Defaults to no value which includes everything. |
+| `--exclude-path \| -e` | No | \*\*/users/\*\* | A glob pattern to exclude paths from generation. Accepts multiple values. Defaults to no value which excludes nothing. |
+| `--language \| -l` | Yes | csharp | The target language for the generated code files or for the information. |
+| `--class-name \| -c` | No | GraphClient | The name of the client class. Defaults to `Client`. |
+| `--namespace-name \| -n` | No | Contoso.GraphApp | The namespace of the client class. Defaults to `Microsoft.Graph`. |
+| `--backing-store \| -b` | No | | Defaults to `false` |
+| `--exclude-backward-compatible \| --ebc` | No |  | Whether to exclude the code generated only for backward compatibility reasons or not. Defaults to `false`. |
+| `--serializer \| -s` | No | `Contoso.Json.CustomSerializer` | One or more module names that implements ISerializationWriterFactory. Default are documented [here](https://learn.microsoft.com/openapi/kiota/using#--serializer--s). |
+| `--deserializer \| --ds` | No | `Contoso.Json.CustomDeserializer` | One or more module names that implements IParseNodeFactory. Default are documented [here](https://learn.microsoft.com/en-us/openapi/kiota/using#--deserializer---ds). |
+| `--structured-mime-types \| -m` | No | `application/json` |Any valid MIME type which will match a request body type or a response type in the OpenAPI description. Default are documented [here](https://learn.microsoft.com/en-us/openapi/kiota/using#--structured-mime-types--m). |
+| `--skip-generation \| --sg` | No | true | When specified, the generation would be skipped. Defaults to false. |
+| `--output \| -o` | No | ./generated/graph/csharp | The output directory or file path for the generated code files. Defaults to `./output`. |
+
+> [!NOTE] 
+> It is not required to use the CLI to add new clients. It is possible to add a new client by adding a new entry in the `clients` section of the `kiota-config.json` file. See the [kiota-config.json schema](../schemas/kiota-config.json.md) for more information.
+
+## Using `kiota client add`
+
+```bash
+kiota client add --client-name "graphDelegated" --openapi "https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/master/openapi/v1.0/openapi.yaml" --include-path "**/users/**" --language csharp --class-name "GraphClient" --namespace-name "Contoso.GraphApp" --backing-store --exclude-backward-compatible --serializer "Contoso.Json.CustomSerializer" --deserializer "Contoso.Json.CustomDeserializer" -structured-mime-types "application/json" --output "./generated/graph/csharp"
+```
+
+```jsonc
+{
+  "clients": {
+    "graphDelegated": {
+      "descriptionHash": "9EDF8506CB74FE44...",
+      "descriptionLocation": "https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/master/openapi/v1.0/openapi.yaml",
+      "includePatterns": ["**/users/**"],
+      "excludePatterns": [],
+      "language": "csharp",
+      "outputPath": "./generated/graph/csharp",
+      "clientClassName": "GraphClient",
+      "clientNamespaceName": "Contoso.GraphApp",
+      "features": {
+        "serializers": [
+          "Contoso.Json.CustomSerializer"
+        ],
+        "deserializers": [
+          "Contoso.Json.CustomDeserializer"
+        ],
+        "structuredMimeTypes": [
+          "application/json"
+        ],
+        "usesBackingStore": true,
+        "includeAdditionalData": true
+      }
+    }
+  }
+}
+```
+
+_The resulting `kiota-config.json` file will look like this:_
+
+```jsonc
+{
+  "version": "1.0.0",
+  "clients": {
+    "graphDelegated": {
+      "descriptionHash": "9EDF8506CB74FE44...",
+      "descriptionLocation": "https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/master/openapi/v1.0/openapi.yaml",
+      "includePatterns": ["**/users/**"],
+      "excludePatterns": [],
+      "language": "csharp",
+      "outputPath": "./generated/graph/csharp",
+      "clientClassName": "GraphClient",
+      "clientNamespaceName": "Contoso.GraphApp",
+      "features": {
+      "serializers": [
+        "Contoso.Json.CustomSerializer"
+      ],
+      "deserializers": [
+        "Contoso.Json.CustomDeserializer"
+      ],
+      "structuredMimeTypes": [
+        "application/json"
+      ],
+      "usesBackingStore": true,
+      "includeAdditionalData": true
+      }
+    }
+  }
+}
+```
+
+_The resulting `apimanifest.json` file will look like this:_
+
+```jsonc
+{
+  "publisher": {
+    "name": "Microsoft Graph",
+    "contactEmail": "[email protected]"
+  },
+  "apiDependencies": {
+    "graphDelegated": {
+      "apiDescriptionUrl": "https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/master/openapi/v1.0/openapi.yaml",
+      "apiDeploymentBaseUrl": "https://graph.microsoft.com",
+      "apiDescriptionVersion": "v1.0",
+      "requests": [
+        {
+          "method": "GET",
+          "uriTemplate": "/users"
+        },
+        {
+          "method": "POST",
+          "uriTemplate": "/users"
+        },
+        {
+          "method": "GET",
+          "uriTemplate": "/users/$count"
+        },
+        {
+          "method": "GET",
+          "uriTemplate": "/users/{user-id}"
+        },
+        {
+          "method": "PATCH",
+          "uriTemplate": "/users/{user-id}"
+        },
+        {
+          "method": "DELETE",
+          "uriTemplate": "/users/{user-id}"
+        }
+      ]
+    }
+  }
+}
+```
+
+## File structure
+```bash
+/
+ └─.kiota
+    └─kiota-config.json
+    └─apimanifest.json
+    └─definitions
+       └─9EDF8506CB74FE44.yaml
+ └─generated
+    └─graph
+       └─csharp
+          └─... # Generated code files
+          └─GraphClient.cs
+```
+
+## Open Questions
+
+- [ ] How do we determine the `name` and `contactEmail` of the `publisher` in the API Manifest? kiota config --global?
+- [ ] Can we automatically generate all `authorizationRequirements` for the endpoints selected or these are left to the developers to add?

specs/cli/client-edit.md

@@ -0,0 +1,156 @@
+# kiota client edit
+
+## Description 
+
+`kiota client update` allows a developer to edit an existing API client int the `kiota-config.json` file. If either the `kiota-config.json` file or if the `--client-name` client can't be found within the `kiota-config.json` file, the command should error out and let the developer know.
+
+When executing, the API entry defined by the `--client-name` parameter will be modified. All parameters should be supported and the only required one is `--client-name`. All others are optional as they would only modify the configuration of the API client. If the OpenAPI description location changed, a new hash of the description will be generated saved as part of the `descriptionHash` property. If `--include-path` or `--exclude-path` are provided, they will be stored in the `includePatterns` and `excludePatterns` properties respectively and would trigger an update to the [API Manifest](https://www.ietf.org/archive/id/draft-miller-api-manifest-01.html#section-2.5-3).
+
+Once the `kiota-config.json` file and the API Manifest are updated, the code generation will be executed based on the newly updated API client configuration.
+
+## Parameters
+
+| Parameters | Required | Example | Description |
+| -- | -- | -- | -- |
+| `--config-location \| --cl` | No | ./.kiota/kiota-config.json | A location where to find or create the `kiota-config.json` file. When not specified it will find an ancestor `kiota-config.json` file and if not found, will use `./.kiota/kiota-config.json`. |
+| `--client-name \| --cn` | Yes | graphDelegated | Name of the client. Unique within the parent API. If not provided, defaults to --class-name or its default. |
+| `--openapi \| -d` | No | https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/master/openapi/v1.0/openapi.yaml | The location of the OpenAPI description in JSON or YAML format to use to generate the SDK. Accepts a URL or a local path. |
+| `--include-path \| -i` | No | /me/chats#GET | A glob pattern to include paths from generation. Accepts multiple values. Defaults to no value which includes everything. |
+| `--exclude-path \| -e` | No | \*\*/users/\*\* | A glob pattern to exclude paths from generation. Accepts multiple values. Defaults to no value which excludes nothing. |
+| `--language \| -l` | No | csharp | The target language for the generated code files or for the information. |
+| `--class-name \| -c` | No | GraphClient | The name of the client class. Defaults to `Client`. |
+| `--namespace-name \| -n` | No | Contoso.GraphApp | The namespace of the client class. Defaults to `Microsoft.Graph`. |
+| `--backing-store \| -b` | No | | Defaults to `false` |
+| `--exclude-backward-compatible \| --ebc` | No |  | Whether to exclude the code generated only for backward compatibility reasons or not. Defaults to `false`. |
+| `--serializer \| -s` | No | `Contoso.Json.CustomSerializer` | One or more module names that implements ISerializationWriterFactory. Default are documented [here](https://learn.microsoft.com/openapi/kiota/using#--serializer--s). |
+| `--deserializer \| --ds` | No | `Contoso.Json.CustomDeserializer` | One or more module names that implements IParseNodeFactory. Default are documented [here](https://learn.microsoft.com/en-us/openapi/kiota/using#--deserializer---ds). |
+| `--structured-mime-types \| -m` | No | `application/json` |Any valid MIME type which will match a request body type or a response type in the OpenAPI description. Default are documented [here](https://learn.microsoft.com/en-us/openapi/kiota/using#--structured-mime-types--m). |
+| `--skip-generation \| --sg` | No | true | When specified, the generation would be skipped. Defaults to false. |
+| `--output \| -o` | No | ./generated/graph/csharp | The output directory or file path for the generated code files. Defaults to `./output`. |
+
+> [!NOTE] 
+> It is not required to use the CLI to edit clients. It is possible to edit a client by modifying its entry in the `clients` section of the `kiota-config.json` file. See the [kiota-config.json schema](../schemas/kiota-config.json.md) for more information.
+
+## Using `kiota client edit`
+
+```bash
+kiota client edit --client-name "graphDelegated" --class-name "GraphServiceClient" --exclude-path "/users/$count"
+```
+
+```jsonc
+{
+  "clients": {
+    "graphDelegated": {
+      "descriptionHash": "9EDF8506CB74FE44...",
+      "descriptionLocation": "https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/master/openapi/v1.0/openapi.yaml",
+      "includePatterns": ["**/users/**"],
+      "excludePatterns": ["/users/$count"],
+      "language": "csharp",
+      "outputPath": "./generated/graph/csharp",
+      "clientClassName": "GraphServiceClient",
+      "clientNamespaceName": "Contoso.GraphApp",
+      "features": {
+        "serializers": [
+          "Contoso.Json.CustomSerializer"
+        ],
+        "deserializers": [
+          "Contoso.Json.CustomDeserializer"
+        ],
+        "structuredMimeTypes": [
+          "application/json"
+        ],
+        "usesBackingStore": true,
+        "includeAdditionalData": true
+      }
+    }
+  }
+}
+```
+
+_The resulting `kiota-config.json` file will look like this:_
+
+```jsonc
+{
+  "version": "1.0.0",
+  "clients": {
+    "graphDelegated": {
+      "descriptionHash": "9EDF8506CB74FE44...",
+      "descriptionLocation": "https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/master/openapi/v1.0/openapi.yaml",
+      "includePatterns": ["**/users/**"],
+      "excludePatterns": [],
+      "language": "csharp",
+      "outputPath": "./generated/graph/csharp",
+      "clientClassName": "GraphServiceClient",
+      "clientNamespaceName": "Contoso.GraphApp",
+      "features": {
+      "serializers": [
+        "Contoso.Json.CustomSerializer"
+      ],
+      "deserializers": [
+        "Contoso.Json.CustomDeserializer"
+      ],
+      "structuredMimeTypes": [
+        "application/json"
+      ],
+      "usesBackingStore": true,
+      "includeAdditionalData": true
+      }
+    }
+  }
+}
+```
+
+_The resulting `apimanifest.json` file will look like this:_
+
+```jsonc
+{
+  "publisher": {
+    "name": "Microsoft Graph",
+    "contactEmail": "[email protected]"
+  },
+  "apiDependencies": {
+    "graphDelegated": {
+      "apiDescriptionUrl": "https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/master/openapi/v1.0/openapi.yaml",
+      "apiDeploymentBaseUrl": "https://graph.microsoft.com",
+      "apiDescriptionVersion": "v1.0",
+      "requests": [
+        {
+          "method": "GET",
+          "uriTemplate": "/users"
+        },
+        {
+          "method": "POST",
+          "uriTemplate": "/users"
+        },
+        {
+          "method": "GET",
+          "uriTemplate": "/users/{user-id}"
+        },
+        {
+          "method": "PATCH",
+          "uriTemplate": "/users/{user-id}"
+        },
+        {
+          "method": "DELETE",
+          "uriTemplate": "/users/{user-id}"
+        }
+      ]
+    }
+  }
+}
+```
+
+## File structure
+```bash
+/
+ └─.kiota
+    └─kiota-config.json
+    └─apimanifest.json
+    └─definitions
+       └─9EDF8506CB74FE44.yaml
+ └─generated
+    └─graph
+       └─csharp
+          └─... # Generated code files
+          └─GraphClient.cs
+```

specs/cli/client-generate.md

@@ -0,0 +1,37 @@
+# kiota client generate
+
+## Description
+
+Now that we have a `kiota-config.json` file, all the parameters required to generate the code are stored in the file. The `kiota client generate` command will read the `kiota-config.json` file and generate the code for each of the available clients. 
+
+It's also possible to specify for which API and client the code should be generated. This is useful when a project contains multiple clients. The `kiota client generate --client-name "MyClient"` command will read the `kiota-config.json` file and generate the code for the specified client. If it can't find the specified API or client, it will throw an error.
+
+In general cases, the `kiota client generate` command will generate the code for all the clients in the `kiota-config.json` file based on the cached OpenAPI description. If the `--refresh` parameter is provided, the command will refresh the cached OpenAPI description(s), update the different `descriptionHash` and then generate the code for the specified clients.
+
+## Parameters
+
+| Parameters | Required | Example | Description |
+| -- | -- | -- | -- |
+| `--config-location \| --cl` | No | ./.kiota/kiota-config.json | A location where to find the `kiota-config.json` file. When not specified it will find an ancestor `kiota-config.json` file and if not found, will use `./.kiota/kiota-config.json`. |
+| `--client-name \| --cn` | No | graphDelegated | Name of the client. Unique within the parent API. |
+| `--refresh \| -r` | No | true | Provided when refreshing the description(s) is required. |
+
+## Usage
+
+### Using `kiota client generate` for a single API client
+
+```bash
+kiota client generate --client-name "graphDelegated"
+```
+
+### Using `kiota client generate` for all API clients
+
+```bash
+kiota client generate
+```
+
+### Using `kiota client generate` for all API clients and refresh their descriptions
+
+```bash
+kiota client generate
+```