README.mustache

# {{packageName}} - the C# library for the {{appName}}

{{#appDescriptionWithNewLines}}
{{{.}}}
{{/appDescriptionWithNewLines}}

{{#useCustomTemplateCode}}
## Migrating from legacy SDK

This SDK is generated from our officially maintained [OpenAPI spec](https://github.com/hellosign/hellosign-openapi/blob/main/openapi.yaml).
We've made important updates that introduce new functionality and create feature parity between the Dropbox Sign API and the SDK.
However, some of these changes are considered "breaking" in the sense that they'll require you to update your existing code in order to continue using the SDK.
Please refer to this [migration guide](https://developers.hellosign.com/docs/sdks/dotnet/migration-guide/) for more information.

## Contributing

This repo is no longer accepting new issues or Pull Requests. All issues or
Pull Requests *must* be opened against the
[hellosign/hellosign-openapi](https://github.com/hellosign/hellosign-openapi) repo!

### Changes to the SDK code

You must make SDK code changes in the mustache file within the `templates`
directory that corresponds to the file you want updated.

{{/useCustomTemplateCode}}
This C# SDK is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) project:

- API version: {{appVersion}}
- SDK version: {{packageVersion}}
{{^hideGenerationTimestamp}}
- Build date: {{generatedDate}}
{{/hideGenerationTimestamp}}
- Generator version: {{generatorVersion}}
- Build package: {{generatorClass}}
{{#infoUrl}}
    For more information, please visit [{{{infoUrl}}}]({{{infoUrl}}})
{{/infoUrl}}

{{#useCustomTemplateCode}}
### Building

You must have `docker` (or `podman` linked to `docker`) installed. Highly
recommended to use
[rootless docker](https://docs.docker.com/engine/security/rootless/).

Run the following and everything is done for you:

```shell
./run-build
```

*Attention*: Any changes you have made to the SDK code that you have not made
to the OAS file and/or the mustache template files _will be lost_ when you run
this command.

{{/useCustomTemplateCode}}
<a id="frameworks-supported"></a>
## Frameworks supported
{{#netStandard}}
- .NET Core >=1.0
- .NET Framework >=4.6
- Mono/Xamarin >=vNext
{{/netStandard}}

<a id="dependencies"></a>
## Dependencies

{{#useRestSharp}}
- [RestSharp](https://www.nuget.org/packages/RestSharp) - 106.13.0 or later
{{/useRestSharp}}
- [Json.NET](https://www.nuget.org/packages/Newtonsoft.Json/) - 13.0.2 or later
- [JsonSubTypes](https://www.nuget.org/packages/JsonSubTypes/) - 1.8.0 or later
{{#useCompareNetObjects}}
- [CompareNETObjects](https://www.nuget.org/packages/CompareNETObjects) - 4.61.0 or later
{{/useCompareNetObjects}}
{{#validatable}}
- [System.ComponentModel.Annotations](https://www.nuget.org/packages/System.ComponentModel.Annotations) - 5.0.0 or later
{{/validatable}}

{{^useCustomTemplateCode}}
The DLLs included in the package may not be the latest version. We recommend using [NuGet](https://docs.nuget.org/consume/installing-nuget) to obtain the latest version of the packages:
```
{{#useRestSharp}}
Install-Package RestSharp
{{/useRestSharp}}
Install-Package Newtonsoft.Json
Install-Package JsonSubTypes
{{#validatable}}
Install-Package System.ComponentModel.Annotations
{{/validatable}}
{{#useCompareNetObjects}}
Install-Package CompareNETObjects
{{/useCompareNetObjects}}
```
{{#useRestSharp}}

NOTE: RestSharp versions greater than 105.1.0 have a bug which causes file uploads to fail. See [RestSharp#742](https://github.com/restsharp/RestSharp/issues/742).
NOTE: RestSharp for .Net Core creates a new socket for each api call, which can lead to a socket exhaustion problem. See [RestSharp#1406](https://github.com/restsharp/RestSharp/issues/1406).

{{/useRestSharp}}
<a id="installation"></a>
## Installation
{{#netStandard}}
Generate the DLL using your preferred tool (e.g. `dotnet build`)
{{/netStandard}}
{{^netStandard}}
Run the following command to generate the DLL
- [Mac/Linux] `/bin/sh build.sh`
- [Windows] `build.bat`
{{/netStandard}}

Then include the DLL (under the `bin` folder) in the C# project, and use the namespaces:
```csharp
using {{packageName}}.{{apiPackage}};
using {{packageName}}.Client;
using {{packageName}}.{{modelPackage}};
```
{{^netStandard}}
<a id="packaging"></a>
## Packaging

A `.nuspec` is included with the project. You can follow the Nuget quickstart to [create](https://docs.microsoft.com/en-us/nuget/quickstart/create-and-publish-a-package#create-the-package) and [publish](https://docs.microsoft.com/en-us/nuget/quickstart/create-and-publish-a-package#publish-the-package) packages.

This `.nuspec` uses placeholders from the `.csproj`, so build the `.csproj` directly:

```
nuget pack -Build -OutputDirectory out {{packageName}}.csproj
```

Then, publish to a [local feed](https://docs.microsoft.com/en-us/nuget/hosting-packages/local-feeds) or [other host](https://docs.microsoft.com/en-us/nuget/hosting-packages/overview) and consume the new package via Nuget as usual.

{{/netStandard}}
{{/useCustomTemplateCode}}
<a id="usage"></a>
{{^useCustomTemplateCode}}
## Usage
{{/useCustomTemplateCode}}
{{#useCustomTemplateCode}}
## Installation & Usage

### NuGet Package Manager

The Dropbox Sign .NET SDK can be installed using the NuGet package manager, under the package name **Dropbox.Sign** ([package details](https://www.nuget.org/packages/Dropbox.Sign)).

### Build from Source

You can follow the NuGet quickstart to [create](https://docs.microsoft.com/en-us/nuget/quickstart/create-and-publish-a-package-using-the-dotnet-cli) and [publish](https://docs.microsoft.com/en-us/nuget/quickstart/create-and-publish-a-package-using-the-dotnet-cli#publish-the-package) the package via the dotnet CLI. Or, you can [create](https://docs.microsoft.com/en-us/nuget/quickstart/create-and-publish-a-package-using-visual-studio?tabs=netcore-cli) and [publish](https://docs.microsoft.com/en-us/nuget/quickstart/create-and-publish-a-package-using-visual-studio?tabs=netcore-cli#publish-the-package) using Visual Studio.

Alternatively, the .nupkg can be published to a [local feed](https://docs.microsoft.com/en-us/nuget/hosting-packages/local-feeds) or [other host](https://docs.microsoft.com/en-us/nuget/hosting-packages/overview) and consumed via NuGet as usual.
{{/useCustomTemplateCode}}

To use the API client with a HTTP proxy, setup a `System.Net.WebProxy`
```csharp
Configuration c = new Configuration();
System.Net.WebProxy webProxy = new System.Net.WebProxy("http://myProxyUrl:80/");
webProxy.Credentials = System.Net.CredentialCache.DefaultCredentials;
c.Proxy = webProxy;
```
{{#useHttpClient}}

### Connections
Each ApiClass (properly the ApiClient inside it) will create an instance of HttpClient. It will use that for the entire lifecycle and dispose it when called the Dispose method.

To better manager the connections it's a common practice to reuse the HttpClient and HttpClientHandler (see [here](https://docs.microsoft.com/en-us/dotnet/architecture/microservices/implement-resilient-applications/use-httpclientfactory-to-implement-resilient-http-requests#issues-with-the-original-httpclient-class-available-in-net) for details). To use your own HttpClient instance just pass it to the ApiClass constructor.

```csharp
HttpClientHandler yourHandler = new HttpClientHandler();
HttpClient yourHttpClient = new HttpClient(yourHandler);
var api = new YourApiClass(yourHttpClient, yourHandler);
```

If you want to use an HttpClient and don't have access to the handler, for example in a DI context in Asp.net Core when using IHttpClientFactory.

```csharp
HttpClient yourHttpClient = new HttpClient();
var api = new YourApiClass(yourHttpClient);
```
You'll loose some configuration settings, the features affected are: Setting and Retrieving Cookies, Client Certificates, Proxy settings. You need to either manually handle those in your setup of the HttpClient or they won't be available.

Here an example of DI setup in a sample web project:

```csharp
services.AddHttpClient<YourApiClass>(httpClient =>
   new PetApi(httpClient));
```

{{/useHttpClient}}

<a id="getting-started"></a>
{{^useCustomTemplateCode}}
## Getting Started

```csharp
using System.Collections.Generic;
using System.Diagnostics;
{{#useHttpClient}}
using System.Net.Http;
{{/useHttpClient}}
using {{packageName}}.{{apiPackage}};
using {{packageName}}.Client;
using {{packageName}}.{{modelPackage}};

namespace Example
{
    public class {{operationId}}Example
    {
        public static void Main()
        {
{{#apiInfo}}{{#apis}}{{#-first}}{{#operations}}{{#operation}}{{#-first}}
            Configuration config = new Configuration();
            config.BasePath = "{{{basePath}}}";
            {{#hasAuthMethods}}
            {{#authMethods}}
            {{#isBasicBasic}}
            // Configure HTTP basic authorization: {{{name}}}
            config.Username = "YOUR_USERNAME";
            config.Password = "YOUR_PASSWORD";
            {{/isBasicBasic}}
            {{#isBasicBearer}}
            // Configure Bearer token for authorization: {{{name}}}
            config.AccessToken = "YOUR_BEARER_TOKEN";
            {{/isBasicBearer}}
            {{#isApiKey}}
            // Configure API key authorization: {{{name}}}
            config.ApiKey.Add("{{{keyParamName}}}", "YOUR_API_KEY");
            // Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
            // config.ApiKeyPrefix.Add("{{{keyParamName}}}", "Bearer");
            {{/isApiKey}}
            {{#isOAuth}}
            // Configure OAuth2 access token for authorization: {{{name}}}
            config.AccessToken = "YOUR_ACCESS_TOKEN";
            {{/isOAuth}}
            {{/authMethods}}

            {{/hasAuthMethods}}
            {{#useHttpClient}}
            // create instances of HttpClient, HttpClientHandler to be reused later with different Api classes
            HttpClient httpClient = new HttpClient();
            HttpClientHandler httpClientHandler = new HttpClientHandler();
            var apiInstance = new {{classname}}(httpClient, config, httpClientHandler);
            {{/useHttpClient}}
            {{^useHttpClient}}
            var apiInstance = new {{classname}}(config);
            {{/useHttpClient}}
            {{#allParams}}
            {{#isPrimitiveType}}
            var {{paramName}} = {{{example}}};  // {{{dataType}}} | {{{description}}}{{^required}} (optional) {{/required}}{{#defaultValue}} (default to {{{.}}}){{/defaultValue}}
            {{/isPrimitiveType}}
            {{^isPrimitiveType}}
            var {{paramName}} = new {{{dataType}}}(); // {{{dataType}}} | {{{description}}}{{^required}} (optional) {{/required}}{{#defaultValue}} (default to {{{.}}}){{/defaultValue}}
            {{/isPrimitiveType}}
            {{/allParams}}

            try
            {
                {{#summary}}
                // {{{.}}}
                {{/summary}}
                {{#returnType}}{{{.}}} result = {{/returnType}}apiInstance.{{{operationId}}}({{#allParams}}{{paramName}}{{^-last}}, {{/-last}}{{/allParams}});{{#returnType}}
                Debug.WriteLine(result);{{/returnType}}
            }
            catch (ApiException e)
            {
                Debug.Print("Exception when calling {{classname}}.{{operationId}}: " + e.Message );
                Debug.Print("Status Code: "+ e.ErrorCode);
                Debug.Print(e.StackTrace);
            }
{{/-first}}{{/operation}}{{/operations}}{{/-first}}{{/apis}}{{/apiInfo}}
        }
    }
}
```
{{/useCustomTemplateCode}}

{{#useCustomTemplateCode}}
## Getting Started

{{#apiInfo}}{{#apis}}{{#-first}}{{#operations}}{{#operation}}{{#-first}}
```csharp
REPLACE_ME_WITH_EXAMPLE_FOR__{{{operationId}}}_C#_CODE
```
{{/-first}}{{/operation}}{{/operations}}{{/-first}}{{/apis}}{{/apiInfo}}
{{/useCustomTemplateCode}}

<a id="documentation-for-api-endpoints"></a>
## Documentation for API Endpoints

All URIs are relative to *{{{basePath}}}*

Class | Method | HTTP request | Description
------------ | ------------- | ------------- | -------------
{{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}*{{classname}}* | [**{{operationId}}**]({{apiDocPath}}{{classname}}.md#{{operationIdLowerCase}}) | **{{httpMethod}}** {{path}} | {{{summary}}}
{{/operation}}{{/operations}}{{/apis}}{{/apiInfo}}

<a id="documentation-for-models"></a>
## Documentation for Models

{{#modelPackage}}
{{#models}}{{#model}} - [{{{modelPackage}}}.{{{classname}}}]({{modelDocPath}}{{{classname}}}.md)
{{/model}}{{/models}}
{{/modelPackage}}
{{^modelPackage}}
No model defined in this package
{{/modelPackage}}

<a id="documentation-for-authorization"></a>
## Documentation for Authorization

{{^authMethods}}Endpoints do not require authorization.{{/authMethods}}
{{#hasAuthMethods}}Authentication schemes defined for the API:{{/hasAuthMethods}}
{{#authMethods}}
<a id="{{name}}"></a>
### {{name}}

{{#isApiKey}}- **Type**: API key
- **API key parameter name**: {{keyParamName}}
- **Location**: {{#isKeyInQuery}}URL query string{{/isKeyInQuery}}{{#isKeyInHeader}}HTTP header{{/isKeyInHeader}}
{{/isApiKey}}
{{#isBasicBasic}}- **Type**: HTTP basic authentication
{{/isBasicBasic}}
{{#isBasicBearer}}- **Type**: Bearer Authentication
{{/isBasicBearer}}
{{#isHttpSignature}}- **Type**: HTTP signature authentication
{{/isHttpSignature}}
{{#isOAuth}}- **Type**: OAuth
- **Flow**: {{flow}}
- **Authorization URL**: {{authorizationUrl}}
- **Scopes**: {{^scopes}}N/A{{/scopes}}
{{#scopes}}  - {{scope}}: {{description}}
{{/scopes}}
{{/isOAuth}}

{{/authMethods}}