README.mustache

# {{artifactId}}

{{^useCustomTemplateCode}}
{{appName}}

- API version: {{appVersion}}
{{^hideGenerationTimestamp}}

- Build date: {{generatedDate}}
{{/hideGenerationTimestamp}}

- Generator version: {{generatorVersion}}

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

{{#infoUrl}}
  For more information, please visit [{{{infoUrl}}}]({{{infoUrl}}})
{{/infoUrl}}

{{^useCustomTemplateCode}}
*Automatically generated by the [OpenAPI Generator](https://openapi-generator.tech)*

## Requirements

Building the API client library requires:

1. Java 1.8+
{{#jersey2}}
2. Maven (3.8.3+)/Gradle (7.2+)
{{/jersey2}}
{{^jersey2}}
2. Maven/Gradle
{{/jersey2}}

## Installation

To install the API client library to your local Maven repository, simply execute:

```shell
mvn clean install
```

To deploy it to a remote Maven repository instead, configure the settings of the repository and execute:

```shell
mvn clean deploy
```

Refer to the [OSSRH Guide](http://central.sonatype.org/pages/ossrh-guide.html) for more information.
{{/useCustomTemplateCode}}
{{#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/java/migration-guide/) for more information.

## Version & Requirements
This is version 2.x of the Java SDK. It depends on Jakarta EE and Jersey 3.

If your project has not been updated for Jakarta or Jersey 3, you should use the [V1 SDK](https://github.com/hellosign/dropbox-sign-java/tree/v1),
which uses Jersey 2 & supports compatibility with Java EEs javax namespace.

Both versions will receive updates so use whichever your application prefers.

## 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.

We use [OpenAPI Generator](https://openapi-generator.tech/) to automatically
generate this SDK from the OAS, using the template files.

### 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}}

### Maven users

Add this dependency to your project's POM:

```xml
<dependency>
  <groupId>{{{groupId}}}</groupId>
  <artifactId>{{{artifactId}}}</artifactId>
  <version>{{{artifactVersion}}}</version>
  <scope>compile</scope>
</dependency>
```

### Gradle users

Add this dependency to your project's build file:

```groovy
  repositories {
    mavenCentral()     // Needed if the '{{{artifactId}}}' jar has been published to maven central.
    mavenLocal()       // Needed if the '{{{artifactId}}}' jar has been published to the local maven repo.
  }

  dependencies {
     implementation "{{{groupId}}}:{{{artifactId}}}:{{{artifactVersion}}}"
  }
```

### Others

At first generate the JAR by executing:

```shell
mvn clean package
```

Then manually install the following JARs:

- `target/{{{artifactId}}}-{{{artifactVersion}}}.jar`
- `target/lib/*.jar`

{{#useCustomTemplateCode}}
## Getting Started

Please follow the [installation](#installation) instruction and execute the following Java code:

{{#apiInfo}}{{#apis}}{{#-first}}{{#operations}}{{#operation}}{{#-first}}
```java
REPLACE_ME_WITH_EXAMPLE_FOR__{{{operationId}}}_Java_CODE
```
{{/-first}}{{/operation}}{{/operations}}{{/-first}}{{/apis}}{{/apiInfo}}

{{/useCustomTemplateCode}}
{{#jersey2}}
{{^useCustomTemplateCode}}
## Usage
{{/useCustomTemplateCode}}
{{#useCustomTemplateCode}}
## Using a Proxy
{{/useCustomTemplateCode}}

To add a HTTP proxy for the API client, use `ClientConfig`:
```java
{{#apiInfo}}{{#apis}}{{#-first}}{{#operations}}{{#operation}}{{#-first}}
import org.glassfish.jersey.apache.connector.ApacheConnectorProvider;
import org.glassfish.jersey.client.ClientConfig;
import org.glassfish.jersey.client.ClientProperties;
import {{{invokerPackage}}}.*;
import {{{package}}}.{{{classname}}};

...

ApiClient defaultClient = Configuration.getDefaultApiClient();
ClientConfig clientConfig = defaultClient.getClientConfig();
clientConfig.connectorProvider(new ApacheConnectorProvider());
clientConfig.property(ClientProperties.PROXY_URI, "http://proxy_url_here");
clientConfig.property(ClientProperties.PROXY_USERNAME, "proxy_username");
clientConfig.property(ClientProperties.PROXY_PASSWORD, "proxy_password");
defaultClient.setClientConfig(clientConfig);

{{{classname}}} apiInstance = new {{{classname}}}(defaultClient);
{{/-first}}{{/operation}}{{/operations}}{{/-first}}{{/apis}}{{/apiInfo}}
```

{{/jersey2}}
{{^useCustomTemplateCode}}
## Getting Started

Please follow the [installation](#installation) instruction and execute the following Java code:

```java
{{#apiInfo}}{{#apis}}{{#-first}}{{#operations}}{{#operation}}{{#-first}}
import {{{invokerPackage}}}.*;
import {{{invokerPackage}}}.auth.*;
import {{{modelPackage}}}.*;
import {{{package}}}.{{{classname}}};

public class {{{classname}}}Example {

    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        defaultClient.setBasePath("{{{basePath}}}");
        {{#hasAuthMethods}}{{#authMethods}}{{#isBasic}}{{#isBasicBasic}}
        // Configure HTTP basic authorization: {{{name}}}
        HttpBasicAuth {{{name}}} = (HttpBasicAuth) defaultClient.getAuthentication("{{{name}}}");
        {{{name}}}.setUsername("YOUR USERNAME");
        {{{name}}}.setPassword("YOUR PASSWORD");{{/isBasicBasic}}{{#isBasicBearer}}
        // Configure HTTP bearer authorization: {{{name}}}
        HttpBearerAuth {{{name}}} = (HttpBearerAuth) defaultClient.getAuthentication("{{{name}}}");
        {{{name}}}.setBearerToken("BEARER TOKEN");{{/isBasicBearer}}{{/isBasic}}{{#isApiKey}}
        // Configure API key authorization: {{{name}}}
        ApiKeyAuth {{{name}}} = (ApiKeyAuth) defaultClient.getAuthentication("{{{name}}}");
        {{{name}}}.setApiKey("YOUR API KEY");
        // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
        //{{{name}}}.setApiKeyPrefix("Token");{{/isApiKey}}{{#isOAuth}}
        // Configure OAuth2 access token for authorization: {{{name}}}
        OAuth {{{name}}} = (OAuth) defaultClient.getAuthentication("{{{name}}}");
        {{{name}}}.setAccessToken("YOUR ACCESS TOKEN");{{/isOAuth}}{{#isHttpSignature}}
        // Configure HTTP signature authorization: {{{name}}}
        HttpSignatureAuth {{{name}}} = (HttpSignatureAuth) defaultClient.getAuthentication("{{{name}}}");
        // All the HTTP signature parameters below should be customized to your environment.
        // Configure the keyId
        {{{name}}}.setKeyId("YOUR KEY ID");
        // Configure the signature algorithm
        {{{name}}}.setSigningAlgorithm(SigningAlgorithm.HS2019);
        // Configure the specific cryptographic algorithm
        {{{name}}}.setAlgorithm(Algorithm.ECDSA_SHA256);
        // Configure the cryptographic algorithm parameters, if applicable
        {{{name}}}.setAlgorithmParameterSpec(null);
        // Set the cryptographic digest algorithm.
        {{{name}}}.setDigestAlgorithm("SHA-256");
        // Set the HTTP headers that should be included in the HTTP signature.
        {{{name}}}.setHeaders(Arrays.asList("date", "host"));
        // Set the private key used to sign the HTTP messages
        {{{name}}}.setPrivateKey();{{/isHttpSignature}}
        {{/authMethods}}
        {{/hasAuthMethods}}

        {{{classname}}} apiInstance = new {{{classname}}}(defaultClient);
        {{#allParams}}
        {{{dataType}}} {{{paramName}}} = {{{example}}}; // {{{dataType}}} | {{{description}}}
        {{/allParams}}
        try {
            {{#returnType}}{{{.}}} result = {{/returnType}}apiInstance.{{{operationId}}}({{#allParams}}{{{paramName}}}{{^-last}}, {{/-last}}{{/allParams}});{{#returnType}}
            System.out.println(result);{{/returnType}}
        } catch (ApiException e) {
            System.err.println("Exception when calling {{{classname}}}#{{{operationId}}}");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}
{{/-first}}{{/operation}}{{/operations}}{{/-first}}{{/apis}}{{/apiInfo}}
```
{{/useCustomTemplateCode}}

## Documentation for API Endpoints

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

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

## Documentation for Models

{{#models}}{{#model}} - [{{classname}}]({{modelDocPath}}{{classname}}.md)
{{/model}}{{/models}}

<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**: HTTP Bearer Token authentication{{#bearerFormat}} ({{{.}}}){{/bearerFormat}}
{{/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}}

## Recommendation

It's recommended to create an instance of `ApiClient` per thread in a multithreaded environment to avoid any potential issues.

## Author

{{#apiInfo}}{{#apis}}{{#-last}}{{infoEmail}}
{{/-last}}{{/apis}}{{/apiInfo}}

{{#useCustomTemplateCode}}
## About this package

This Java package is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) project:

- API version: `{{appVersion}}`
{{#artifactVersion}}
    - Package version: `{{.}}`
{{/artifactVersion}}
{{^hideGenerationTimestamp}}
    - Build date: `{{generatedDate}}`
{{/hideGenerationTimestamp}}
- Build package: `{{generatorClass}}`


# Working on this SDK

This section includes documentation about how to generate the SDK in case you want to make a contribution.

## Building the SDK with Docker

Run `./run-build`

## Installation / Deployment

To install the API client library to your local Maven repository, simply execute:

```shell
mvn clean install
```

To deploy it to a remote Maven repository instead, configure the settings of the repository and execute:

```shell
mvn clean deploy
```

Refer to the [OSSRH Guide](http://central.sonatype.org/pages/ossrh-guide.html) for more information.
{{/useCustomTemplateCode}}