README.mustache

# Rust API for {{{packageName}}}

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

## Overview

This client/server was generated by the [openapi-generator]
(https://openapi-generator.tech) project.  By using the
[OpenAPI-Spec](https://github.com/OAI/OpenAPI-Specification) from a remote
server, you can easily generate a server stub.

To see how to make this your own, look here:

[README]((https://openapi-generator.tech))

- API version: {{{appVersion}}}
{{^hideGenerationTimestamp}}
- Build date: {{{generatedDate}}}
{{/hideGenerationTimestamp}}
- Generator version: {{generatorVersion}}

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

This autogenerated project defines an API crate `{{{packageName}}}` which contains:
* An `Api` trait defining the API in Rust.
* Data types representing the underlying data model.
* A `Client` type which implements `Api` and issues HTTP requests for each operation.
* A router which accepts HTTP requests and invokes the appropriate `Api` method for each operation.
* A CLI tool to drive basic API operations from the command line.

It also contains an example server and client which make use of `{{{packageName}}}`:

* The example server starts up a web server using the `{{{packageName}}}`
    router, and supplies a trivial implementation of `Api` which returns failure
    for every operation.
* The example client provides a CLI which lets you invoke
    any single operation on the `{{{packageName}}}` client by passing appropriate
    arguments on the command line.

You can use the example server and client as a basis for your own code.
See below for [more detail on the examples](#using-the-generated-library).

## CLI

Run the included CLI tool with:

```
cargo run --bin cli --features=cli
```

To pass in arguments, put them after `--`, for example:

```
cargo run --bin cli --features=cli -- --help
```

See the help text for available options.

To build a standalone tool, use:

```
cargo build --bin cli --features=cli --release
```

You'll find the binary at `target/release/cli`.

## Examples

Run examples with:

```
cargo run --example {{{packageName}}}-<client|server>
```

To pass in arguments to the examples, put them after `--`, for example:

```
cargo run --example {{{packageName}}}-client -- --help
```

### Running the example server
To run the server, follow these simple steps:

```
cargo run --example {{{packageName}}}-server
```

### Running the example client
To run a client, follow one of the following simple steps:

```
{{#apiInfo}}
  {{#apis}}
    {{#operations}}
      {{#operation}}
        {{#exts}}
          {{^x-no-client-example}}
cargo run --example {{{packageName}}}-client {{{operationId}}}
          {{/x-no-client-example}}
        {{/exts}}
      {{/operation}}
    {{/operations}}
  {{/apis}}
{{/apiInfo}}
```

### HTTPS
The examples can be run in HTTPS mode by passing in the flag `--https`, for example:

```
cargo run --example {{{packageName}}}-server -- --https
```

This will use the keys/certificates from the examples directory. Note that the
server chain is signed with `CN=localhost`.

## Using the generated library

The generated library has a few optional features that can be activated through Cargo.

* `server`
    * This defaults to enabled and creates the basic skeleton of a server implementation based on hyper
    * To create the server stack you'll need to provide an implementation of the API trait to provide the server function.
* `client`
    * This defaults to enabled and creates the basic skeleton of a client implementation based on hyper
    * The constructed client implements the API trait by making remote API call.
* `client-tls`
    * This default to enabled and provides HTTPS support with automatic TLS backend selection:
        - macOS/Windows/iOS: native-tls + hyper-tls
        - Linux/Unix/others: OpenSSL + hyper-openssl
* `conversions`
    * This defaults to disabled and creates extra derives on models to allow "transmogrification" between objects of structurally similar types.
* `cli`
    * This defaults to disabled and is required for building the included CLI tool.
* `validate`
    * This defaults to disabled and allows JSON Schema validation of received data using `MakeService::set_validation` or `Service::set_validation`.
    * Note, enabling validation will have a performance penalty, especially if the API heavily uses regex based checks.

### HTTPS/TLS Support

HTTPS support is included by default. To disable it (for example, to reduce dependencies), you can:

```toml
[dependencies]
{{{packageName}}} = { version = "{{{packageVersion}}}", default-features = false, features = ["client", "server"] }
```

**For server with callbacks that need HTTPS:**
```toml
[dependencies]
{{{packageName}}} = { version = "{{{packageVersion}}}", features = ["server", "client-tls"] }
```

The TLS backend is automatically selected based on your target platform:
- **macOS, Windows, iOS**: Uses `native-tls` (system TLS libraries)
- **Linux, Unix, other platforms**: Uses `openssl`

See https://doc.rust-lang.org/cargo/reference/manifest.html#the-features-section for how to use features in your `Cargo.toml`.

## Documentation for API Endpoints

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

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

## Documentation For Models

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

## Documentation For Authorization
{{^authMethods}}Endpoints do not require authorization.{{/authMethods}}
{{#hasAuthMethods}}Authentication schemes defined for the API:{{/hasAuthMethods}}
{{#authMethods}}
### {{{name}}}
{{#isApiKey}}- **Type**: API key

Example
```
	{{! TODO: Add API Key example }}
```
{{/isApiKey}}
{{#isBasicBasic}}- **Type**: HTTP basic authentication

Example
```
	{{! TODO: Add HTTP basic authentication }}
```
{{/isBasicBasic}}
{{#isBasicBearer}}- **Type**: Bearer token authentication

Example
```
	{{! TODO: Add Bearer token 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}}

Example
```
	{{! TODO: OAuth example }}
```

Or via OAuth2 module to automatically refresh tokens and perform user authentication.
```
	{{! TODO: OAuth example }}
```
{{/isOAuth}}
{{/authMethods}}

## Author

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