rust-server.README.mustache Maven / Gradle / Ivy
# Rust API for {{{packageName}}}
{{#appDescription}}
{{{appDescription}}}
{{/appDescription}}
## 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}}
{{#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.
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 implementing a server](#writing-a-server).
## Examples
Run examples with:
```
cargo run --example
```
To pass in arguments to the examples, put them after `--`, for example:
```
cargo run --example client -- --help
```
### Running the server
To run the server, follow these simple steps:
```
cargo run --example server
```
### Running a client
To run a client, follow one of the following simple steps:
```{{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}
cargo run --example client {{{operationId}}}{{/operation}}{{/operations}}{{/apis}}{{/apiInfo}}
```
### HTTPS
The examples can be run in HTTPS mode by passing in the flag `--https`, for example:
```
cargo run --example server -- --https
```
This will use the keys/certificates from the examples directory. Note that the server chain is signed with
`CN=localhost`.
## Writing a server
The server example is designed to form the basis for implementing your own server. Simply follow these steps.
* Set up a new Rust project, e.g., with `cargo init --bin`.
* Insert `{{{packageName}}}` into the `members` array under [workspace] in the root `Cargo.toml`, e.g., `members = [ "{{{packageName}}}" ]`.
* Add `{{{packageName}}} = {version = "{{{appVersion}}}", path = "{{{packageName}}}"}` under `[dependencies]` in the root `Cargo.toml`.
* Copy the `[dependencies]` and `[dev-dependencies]` from `{{{packageName}}}/Cargo.toml` into the root `Cargo.toml`'s `[dependencies]` section.
* Copy all of the `[dev-dependencies]`, but only the `[dependencies]` that are required by the example server. These should be clearly indicated by comments.
* Remove `"optional = true"` from each of these lines if present.
Each autogenerated API will contain an implementation stub and main entry point, which should be copied into your project the first time:
```
cp {{{packageName}}}/examples/server.rs src/main.rs
cp {{{packageName}}}/examples/server_lib/mod.rs src/lib.rs
cp {{{packageName}}}/examples/server_lib/server.rs src/server.rs
```
Now
* From `src/main.rs`, remove the `mod server_lib;` line, and uncomment and fill in the `extern crate` line with the name of this server crate.
* Move the block of imports "required by the service library" from `src/main.rs` to `src/lib.rs` and uncomment.
* Change the `let server = server::Server {};` line to `let server = SERVICE_NAME::server().unwrap();` where `SERVICE_NAME` is the name of the server crate.
* Run `cargo build` to check it builds.
* Run `cargo fmt` to reformat the code.
* Commit the result before making any further changes (lest format changes get confused with your own updates).
Now replace the implementations in `src/server.rs` with your own code as required.
## Updating your server to track API changes
Later, if the API changes, you can copy new sections from the autogenerated API stub into your implementation.
Alternatively, implement the now-missing methods based on the compiler's error messages.
## 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}}{{{summary}}}{{/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}}{{#authMethods}}{{#last}} Authentication schemes defined for the API:{{/last}}{{/authMethods}}
{{#authMethods}}
## {{{name}}}
{{#isApiKey}}- **Type**: API key
Example
```
{{! TODO: Add API Key example }}
```
{{/isApiKey}}
{{#isBasic}}- **Type**: HTTP basic authentication
Example
```
{{! TODO: Add HTTP basic authentication }}
```
{{/isBasic}}
{{#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}}{{^hasMore}}{{{infoEmail}}}
{{/hasMore}}{{/apis}}{{/apiInfo}}