Skip to content

Commit 920522a

Browse files
luanbrdevLuanbrricardozanini
authored
Migrate to Quarkiverse Docs from main README (#493)
Migrate to Quarkiverse Docs from main README --------- Co-authored-by: luanbramalho <[email protected]> Co-authored-by: Ricardo Zanini <[email protected]>
1 parent 8851bca commit 920522a

13 files changed

+958
-842
lines changed

‎README.md‎

Lines changed: 2 additions & 830 deletions
Large diffs are not rendered by default.

‎docs/modules/ROOT/pages/includes/authentication-support.adoc‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
If your OpenAPI specification file has `securitySchemes` https://spec.openapis.org/oas/v3.1.0#security-scheme-object[definitions], the inner generator
2+
will https://download.eclipse.org/microprofile/microprofile-rest-client-2.0/microprofile-rest-client-spec-2.0.html#_provider_declaration[register ClientRequestFilter providers] for you to
3+
implement the given authentication mechanism.
4+
5+
To provide the credentials for your application, you can use the https://quarkus.io/guides/config[Quarkus configuration support]. The configuration key is composed using this
6+
pattern: `quarkus.openapi-generator.[filename].auth.[security_scheme_name].[auth_property_name]`. Where:
7+
8+
* `filename` is the sanitized name of file containing the OpenAPI spec, for example `petstore_json`.
9+
* `security_scheme_name` is the sanitized name of the https://spec.openapis.org/oas/v3.1.0#security-scheme-object[security scheme object definition] in the OpenAPI file. Given the following excerpt, we
10+
have `api_key` and `basic_auth` security schemes:
11+
12+
[source,json]
13+
----
14+
{
15+
"securitySchemes": {
16+
"api_key": {
17+
"type": "apiKey",
18+
"name": "api_key",
19+
"in": "header"
20+
},
21+
"basic_auth": {
22+
"type": "http",
23+
"scheme": "basic"
24+
}
25+
}
26+
}
27+
----
28+
29+
WARNING: Note that the securityScheme name used to configure the specific information for each spec is sanitized using the same rules as for the file names.
30+
31+
* `auth_property_name` varies depending on the authentication provider. For example, for Basic Authentication we have `username` and `password`. See the following sections for more details.
32+
33+
> Tip: on production environments you will likely to use https://quarkiverse.github.io/quarkiverse-docs/quarkus-vault/dev/index.html[HashiCorp Vault] or https://kubernetes.io/docs/concepts/configuration/secret/[Kubernetes Secrets] to provide this information for your application.
34+
35+
If the OpenAPI specification file has `securitySchemes` definitions, but no https://spec.openapis.org/oas/v3.1.0#security-requirement-object[Security Requirement Object] definitions, the generator can be configured to create these by default. In this case, for all operations without a security requirement the default one will be created. Note that the property value needs to match the name of a security scheme object definition, eg. `api_key` or `basic_auth` in the `securitySchemes` list above.
36+
37+
38+
[%autowidth]
39+
|===
40+
|Description |Property Key |Example
41+
42+
|Create security for the referenced security scheme
43+
|`quarkus.openapi-generator.codegen.default-security-scheme`
44+
|`quarkus.openapi-generator.codegen.default-security-scheme=api_key`
45+
|===
46+
47+
See the module https://github.com/quarkiverse/quarkus-openapi-generator/tree/main/integration-tests/security[security] for an example of how to use this feature.
48+
49+
== Basic HTTP Authentication
50+
51+
For Basic HTTP Authentication, these are the supported configurations:
52+
53+
[%autowidth]
54+
|===
55+
|Description |Property Key |Example
56+
57+
|Username credentials
58+
|`quarkus.openapi-generator.[filename].auth.[security_scheme_name].username`
59+
| `quarkus.openapi-generator.petstore_json.auth.basic_auth.username`
60+
|Password credentials
61+
|`quarkus.openapi-generator.[filename].auth.[security_scheme_name].password`
62+
|`quarkus.openapi-generator.petstore_json.auth.basic_auth-password`
63+
|===
64+
65+
== Bearer Token Authentication
66+
67+
Authentication, these are the supported configurations:
68+
69+
[%autowidth]
70+
|===
71+
|Description |Property Key |Example
72+
73+
|Bearer Token
74+
|`quarkus.openapi-generator.[filename].auth.[security_scheme_name].bearer-token`
75+
|`quarkus.openapi-generator.petstore_json.auth.bearer.bearer-token`
76+
|===
77+
78+
== API Key Authentication
79+
80+
Similarly to bearer token, the API Key Authentication also has the token entry key property:
81+
82+
[%autowidth]
83+
|===
84+
|Description |Property Key |Example
85+
86+
|API Key
87+
|`quarkus.openapi-generator.[filename].auth.[security_scheme_name].api-key`
88+
|`quarkus.openapi-generator.petstore_json.auth.api_key.api-key`
89+
|===
90+
91+
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.
92+
93+
== OAuth2 Authentication
94+
95+
The extension will generate a `ClientRequestFilter` capable to add OAuth2 authentication capabilities to the OpenAPI operations that require it. This means that you can use
96+
the https://quarkus.io/guides/security-openid-connect-client[Quarkus OIDC Extension] configuration to define your authentication flow.
97+
98+
The generated code creates a named `OidcClient` for each https://spec.openapis.org/oas/v3.1.0#security-scheme-object[Security Scheme] listed in the OpenAPI specification files. For example, given
99+
the following excerpt:
100+
101+
[source,json]
102+
----
103+
{
104+
"securitySchemes": {
105+
"petstore_auth": {
106+
"type": "oauth2",
107+
"flows": {
108+
"implicit": {
109+
"authorizationUrl": "https://petstore3.swagger.io/oauth/authorize",
110+
"scopes": {
111+
"write:pets": "modify pets in your account",
112+
"read:pets": "read your pets"
113+
}
114+
}
115+
}
116+
}
117+
}
118+
}
119+
----
120+
121+
You can configure this `OidcClient` as:
122+
123+
[source,properties]
124+
----
125+
quarkus.oidc-client.petstore_auth.auth-server-url=https://petstore3.swagger.io/oauth/authorize
126+
quarkus.oidc-client.petstore_auth.discovery-enabled=false
127+
quarkus.oidc-client.petstore_auth.token-path=/tokens
128+
quarkus.oidc-client.petstore_auth.credentials.secret=secret
129+
quarkus.oidc-client.petstore_auth.grant.type=password
130+
quarkus.oidc-client.petstore_auth.grant-options.password.username=alice
131+
quarkus.oidc-client.petstore_auth.grant-options.password.password=alice
132+
quarkus.oidc-client.petstore_auth.client-id=petstore-app
133+
----
134+
135+
The configuration suffix `quarkus.oidc-client.petstore_auth` is exclusive for the schema defined in the specification file and the `schemaName` is sanitized by applying the rules described above.
136+
137+
For this to work you **must** add https://quarkus.io/guides/security-openid-connect-client#oidc-client-filter[Quarkus OIDC Client Filter Extension] to your project:
138+
139+
RESTEasy Classic:
140+
141+
[source ,xml]
142+
----
143+
<dependency>
144+
<groupId>io.quarkus</groupId>
145+
<artifactId>quarkus-oidc-client-filter</artifactId>
146+
</dependency>
147+
----
148+
149+
RESTEasy Reactive:
150+
151+
[source ,xml]
152+
----
153+
<dependency>
154+
<groupId>io.quarkus</groupId>
155+
<artifactId>quarkus-oidc-client-reactive-filter</artifactId>
156+
</dependency>
157+
----
158+
159+
If authentication support doesn't suit your needs you can decide to disable it with `enable-security-generation=false`. In such case CompositeAuthenticationProvider and AuthenticationPropagationHeadersFactory wont be generated and used with your api.
160+
The option can be set globally with `quarkus.openapi-generator.codegen.enable-security-generation` or per api `quarkus.openapi-generator.codegen.spec.my_spec_yml.enable-security-generation`
161+
Custom authentication provider can be used with `additional-api-type-annotations`
162+
163+
See the module https://github.com/quarkiverse/quarkus-openapi-generator/tree/main/integration-tests/generation-tests[generation-tests] for an example of how to use this feature.

‎docs/modules/ROOT/pages/includes/authorization-token-propagation.adoc‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
The authorization token propagation can be used with OpenApi operations secured with a security scheme of type "oauth2" or "bearer".
2+
When configured, you can propagate the authorization tokens passed to your service and the invocations to the REST clients generated by the quarkus-openapi-generator.
3+
4+
Let's see how it works by following a simple example:
5+
6+
Imagine that we have a `updatePet` operation defined in the `petstore.json` specification file and secured with the `petstore_auth` security scheme.
7+
The code below shows a simple example of the usage of this operation in a user-programmed service.
8+
9+
[source ,java]
10+
----
11+
import org.acme.api.PetApi;
12+
import org.acme.model.Pet;
13+
import org.eclipse.microprofile.rest.client.inject.RestClient;
14+
15+
/**
16+
* User programmed service.
17+
*/
18+
@Path("/petstore")
19+
public class PetResource {
20+
21+
/**
22+
* Inject the rest client generated by the quarkus-openapi-generator.
23+
*/
24+
@Inject
25+
@RestClient
26+
PetApi petApi;
27+
28+
/**
29+
* User programmed operation.
30+
*/
31+
@Path("/pet/{id}")
32+
@PATCH
33+
@Produces(MediaType.APPLICATION_JSON)
34+
@Consumes(MediaType.APPLICATION_JSON)
35+
public Response customUpdatePet(@PathParam("id") long id, PetData petData) {
36+
37+
// Create a new instance of the Pet class generated by the quarkus-openapi-generator and
38+
// populate accordingly.
39+
Pet pet = new Pet();
40+
pet.setId(id);
41+
applyDataToPet(pet, petData);
42+
43+
// Execute the rest call using the generated client.
44+
// The petstore.json open api spec stays that the "updatePet" operation is secured with the
45+
// security scheme "petstore_auth".
46+
petApi.updatePet(pet);
47+
48+
// Do other required things and finally return something.
49+
return Response.ok().build();
50+
}
51+
52+
public static class PetData {
53+
// Represents the Pet modifiable data sent to the user programmed service.
54+
}
55+
56+
private void applyDataToPet(Pet pet, PetData petData) {
57+
// Set the corresponding values to the Pet instance.
58+
}
59+
}
60+
----
61+
62+
Let's see what happens when the PetResource service `customUpdatePet` operation is invoked by a third party.
63+
64+
== Default flow
65+
66+
. The `customUpdatePet` operation is invoked.
67+
. An authorization token is obtained using the corresponding `petstore_auth` OidcClient configuration. (for more information see <<_oauth2_authentication>>)
68+
. The authorization token is automatically passed along the PetApi `updatePet` operation execution using an automatically generated request filter, etc.
69+
70+
=== Propagation flow
71+
72+
However, there are scenarios where we want to propagate the authorization token that was initially passed to the PetResource service when the `customUpdatePet` operation was invoked instead of having to obtain it by using the `OidcClient`.
73+
74+
. The user service `customUpdatePet` operation is invoked, and an authorization token is passed by the third party typically by using the HTTP `Authorization` header.
75+
. The incoming authorization token is automatically passed along the PetApi `updatePet` operation execution according to the user-provided configuration.
76+
77+
WARNING: When configured, the token propagation applies to all the operations secured with the same `securityScheme` in the same specification file.
78+
79+
=== Propagation flow configuration
80+
81+
The token propagation can be used with type "oauth2" or "bearer" security schemes. Finally, considering that a given security scheme might be configured on a set of operations in the same specification file when configured, it'll apply to all these operations.
82+
83+
[%autowidth]
84+
|===
85+
|Property Key |Example
86+
87+
|`quarkus.openapi-generator.[filename].auth.[security_scheme_name].token-propagation=[true,false]`
88+
|`quarkus.openapi-generator.petstore_json.auth.petstore_auth.token-propagation=true` +
89+
Enables the token propagation for all the operations that are secured with the `petstore_auth` scheme in the `petstore_json` file.
90+
|`quarkus.openapi-generator.[filename].auth.[security_scheme_name].header-name=[http_header_name]`
91+
|`quarkus.openapi-generator.petstore_json.auth.petstore_auth.header-name=MyHeaderName` +
92+
Says that the authorization token to propagate will be read from the HTTP header `MyHeaderName` instead of the standard HTTP `Authorization` header.
93+
|===

‎docs/modules/ROOT/pages/includes/circuit-breaker.adoc‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
2+
You can define the https://microprofile.io/project/eclipse/microprofile-fault-tolerance/spec/src/main/asciidoc/circuitbreaker.asciidoc[CircuitBreaker annotation from MicroProfile Fault Tolerance]
3+
in your generated classes by setting the desired configuration in `application.properties`.
4+
5+
Let's say you have the following OpenAPI definition:
6+
7+
[source ,json]
8+
----
9+
{
10+
"openapi": "3.0.3",
11+
"info": {
12+
"title": "Simple API",
13+
"version": "1.0.0-SNAPSHOT"
14+
},
15+
"paths": {
16+
"/hello": {
17+
"get": {
18+
"responses": {
19+
"200": {
20+
"description": "OK",
21+
"content": {
22+
"text/plain": {
23+
"schema": {
24+
"type": "string"
25+
}
26+
}
27+
}
28+
}
29+
}
30+
}
31+
},
32+
"/bye": {
33+
"get": {
34+
"responses": {
35+
"200": {
36+
"description": "OK",
37+
"content": {
38+
"text/plain": {
39+
"schema": {
40+
"type": "string"
41+
}
42+
}
43+
}
44+
}
45+
}
46+
}
47+
}
48+
}
49+
}
50+
----
51+
52+
And you want to configure Circuit Breaker for the `/bye` endpoint, you can do it in the following way:
53+
54+
Add the https://quarkus.io/guides/smallrye-fault-tolerance[SmallRye Fault Tolerance extension] to your project's `pom.xml` file:
55+
56+
[source ,xml]
57+
----
58+
<dependency>
59+
<groupId>io.quarkus</groupId>
60+
<artifactId>quarkus-smallrye-fault-tolerance</artifactId>
61+
</dependency>
62+
----
63+
64+
Assuming your Open API spec file is in `src/main/openapi/simple-openapi.json`, add the following configuration to your `application.properties` file:
65+
66+
[source ,properties]
67+
----
68+
# Note that the file name must have only alphabetic characters or underscores (_).
69+
quarkus.openapi-generator.codegen.spec.simple_openapi_json.base-package=org.acme.openapi.simple
70+
# Enables the CircuitBreaker extension for the byeGet method from the DefaultApi class
71+
org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/enabled=true
72+
----
73+
74+
With the above configuration, your Rest Clients will be created with a code similar to the following:
75+
76+
[source ,java]
77+
----
78+
package org.acme.openapi.simple.api;
79+
80+
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
81+
82+
import java.io.InputStream;
83+
import java.io.OutputStream;
84+
import java.util.List;
85+
import java.util.Map;
86+
87+
import jakarta.ws.rs.*;
88+
import jakarta.ws.rs.core.Response;
89+
import jakarta.ws.rs.core.MediaType;
90+
91+
@Path("")
92+
@RegisterRestClient(configKey="simple-openapi_json")
93+
public interface DefaultApi {
94+
95+
@GET
96+
@Path("/bye")
97+
@Produces({ "text/plain" })
98+
@org.eclipse.microprofile.faulttolerance.CircuitBreaker
99+
public String byeGet();
100+
101+
@GET
102+
@Path("/hello")
103+
@Produces({ "text/plain" })
104+
public String helloGet();
105+
106+
}
107+
----
108+
109+
You can also override the default Circuit Breaker configuration by setting the properties
110+
in `application.properties` https://quarkus.io/guides/smallrye-fault-tolerance#runtime-configuration[just as you would for a traditional MicroProfile application]:
111+
112+
[source ,properties]
113+
----
114+
org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/failOn=java.lang.IllegalArgumentException,java.lang.NullPointerException
115+
org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/skipOn=java.lang.NumberFormatException
116+
org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/delay=33
117+
org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/delayUnit=MILLIS
118+
org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/requestVolumeThreshold=42
119+
org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/failureRatio=3.14
120+
org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/successThreshold=22
121+
----
122+
123+
See the module https://github.com/quarkiverse/quarkus-openapi-generator/tree/main/integration-tests/circuit-breaker[circuit-breaker] for an example of how to use this feature.

0 commit comments

Comments
 (0)