What is this?
This PR will add integration with Microsoft's Generic Host. The host manages application lifetime, dependency injection, application configuration, and much more. This library will provide extension methods for the host. This makes it easy to integrate a generated API wrapper into an existing application.
How do I use this?
Here is sample code showing what it looks like to use this library.
public class Program
{
public static async Task Main(string[] args)
{
var host = CreateHostBuilder(args).Build();
IFooApi fooApi = host.Services.GetRequiredService<IFooApi>();
Foo foo = await fooApi.GetFooAsync("todo");
}
public static IHostBuilder CreateHostBuilder(string[] args) => Host.CreateDefaultBuilder(args)
.ConfigureApi((context, options) =>
{
ApiKeyToken token = new("<your token>");
options.AddTokens(token);
// optionally configure the token provider strategy, default is RateLimitProvider
options.UseProvider<RateLimitProvider<ApiKeyToken>, ApiKeyToken>();
options.ConfigureJsonOptions((jsonOptions) =>
{
// your custom converters if any
});
options.AddApiHttpClients(builder: builder => builder
.AddRetryPolicy(2)
.AddTimeoutPolicy(TimeSpan.FromSeconds(5))
.AddCircuitBreakerPolicy(10, TimeSpan.FromSeconds(30))
// any other middleware
);
});
}
Other Changes
api.mustache
The api.mustache template was also rewritten to take full advantage of proper dependency injection. There is also no longer a need for the Configuration class, so this was another reason to make changes in this class.
Tokens
Each type of security protocol (like JWT and others) will generate a different class to represent the token. This class will store the token's credentials as well as a timespan. The timespan is used in client side rate limiting so we can ensure we don't get server throttled.
RateLimitProvider
This class provides tokens to the IFooApi. Tokens will be rate limited at the client side to ensure we do not get rate limited by the server. The token timeout is defined in the token's constructor.
TokenContainer
This is an internally used class that end users don't have to see. It merely holds the tokens in a way that is conducive for dependency injection.
HostConfiguration
This class is used by extension methods on the generic host.
ApiResponse<T> and ApiException
When do we expect exceptions when the response is not 200?
- GetFooAsyncWithHttpInfo -> will not throw but HttpStatus is in the ApiResponse<T>
- GetFooAsync -> will throw
- GetFooOrDefaultAsync -> will return null
Future Changes
- full annotation of nullable reference types
- migrate to System.Text.Json
PR checklist
-
Read the contribution guidelines. -
Pull Request title clearly describes the work in the pull request and Pull Request description provides details about how to validate the work. Missing information here may result in delayed response from the community. -
Run the following to build the project and update samples: ./mvnw clean package ./bin/generate-samples.sh ./bin/utils/export_docs_generators.sh
./bin/generate-samples.sh bin/configs/java*
. For Windows users, please run the script in Git BASH. -
File the PR against the correct branch: master
(5.3.0),6.0.x
-
If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request.