Quarkus' extension for generation of Rest Clients based on OpenAPI specification files.
This extension is based on the OpenAPI Generator Tool.
Add the following dependency to your project's pom.xml
file:
<dependency>
<groupId>io.quarkiverse.openapi.generator</groupId>
<artifactId>quarkus-openapi-generator</artifactId>
<version>0.1.0</version>
</dependency>
You will also need to add or update the quarkus-maven-plugin
configuration with the following:
⚠️ You probably already have this configuration if you created your application with the Quarkus Starter. That said, double-check your configuration not to add anotherplugin
entry.
<plugin>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-maven-plugin</artifactId>
<extensions>true</extensions>
<executions>
<execution>
<goals>
<goal>build</goal>
<goal>generate-code</goal>
<goal>generate-code-tests</goal>
</goals>
</execution>
</executions>
</plugin>
Now, create the directory openapi
under your src/main/
path and add the OpenAPI spec files there. We support JSON, YAML and YML extensions.
To fine tune the configuration for each spec file, add the following entry to your properties file. In this example, our spec file is in src/main/openapi/petstore.json
:
quarkus.openapi-generator.codegen.spec."petstore.json".base-package=org.acme.openapi
Note that the file name is used to configure the specific information for each spec.
Run mvn compile
to generate your classes in target/generated-sources/open-api-json
path:
- org.acme.openapi
- api
- PetApi.java
- StoreApi.java
- UserApi.java
- model
- Address.java
- Category.java
- Customer.java
- ModelApiResponse.java
- Order.java
- Pet.java
- Tag.java
- User.java
You can reference the generated code in your project, for example:
import javax.inject.Inject;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
import org.acme.openapi.api.PetApi;
import org.eclipse.microprofile.rest.client.inject.RestClient;
import org.jboss.resteasy.annotations.jaxrs.PathParam;
@Produces(MediaType.APPLICATION_JSON)
@Path("/petstore")
public class PetResource {
@RestClient
@Inject
PetApi petApi;
}
See the integration-tests module for more information of how to use this extension. Please be advised that the extension is on experimental, early development stage.
If your OpenAPI specification file has securitySchemes
definitions, the inner generator will register ClientRequestFilter
s providers for you to implement the given authentication mechanism.
To provide the credentials for your application, you can use the Quarkus configuration support. The configuration key is composed using this pattern: [base_package].security.auth.[security_scheme_name]/[auth_property_name]
. Where:
base_package
is the package name you gave when configuring the code generation usingquarkus.openapi-generator.codegen.spec.[open_api_file].base-package
property.security_scheme_name
is the name of the security scheme object definition in the OpenAPI file. Given the following excerpt, we haveapi_key
andbasic_auth
security schemes:
{
"securitySchemes": {
"api_key": {
"type": "apiKey",
"name": "api_key",
"in": "header"
},
"basic_auth": {
"type": "http",
"scheme": "basic"
}
}
}
auth_property_name
varies depending on the authentication provider. For example, for Basic Authentication we haveusername
andpassword
. See the following sections for more details.
Tip: on production environments you will likely to use HashiCorp Vault or Kubernetes Secrets to provide this information for your application.
For Basic HTTP Authentication, these are the supported configurations:
Description | Property Key | Example |
---|---|---|
Username credentials | [base_package].security.auth.[security_scheme_name]/username |
org.acme.openapi.security.auth.basic_auth/username |
Password credentials | [base_package].security.auth.[security_scheme_name]/password |
org.acme.openapi.security.auth.basic_auth/password |
For Bearer Token Authentication, these are the supported configurations:
Description | Property Key | Example |
---|---|---|
Bearer Token | [base_package].security.auth.[security_scheme_name]/bearer-token |
org.acme.openapi.security.auth.bearer/bearer-token |
Similarly to bearer token, the API Key Authentication also has the token entry key property:
Description | Property Key | Example |
---|---|---|
API Key | [base_package].security.auth.[security_scheme_name]/api-key |
org.acme.openapi.security.auth.apikey/api-key |
The API Key scheme has an additional property that requires where to add the API key in the request token: header, cookie or query. The inner provider takes care of that for you.
These are the known limitations of this pre-release version:
- No OAuth2 support
- No reactive support
- Only Jackson support
We will work in the next few releases to address these use cases, until there please provide feedback for the current state of this extension. We also love contributions ❤️
Thanks goes to these wonderful people (emoji key):
Ricardo Zanini 💻 🚧 |
Helber Belmiro 📖 |
George Gastaldi 💻 🚇 |
Rishi Kumar Ray 🚇 |
This project follows the all-contributors specification. Contributions of any kind welcome!