diff --git a/EpcQrCodeRest/build.gradle b/EpcQrCodeRest/build.gradle index 3b36cfc..8026814 100644 --- a/EpcQrCodeRest/build.gradle +++ b/EpcQrCodeRest/build.gradle @@ -35,6 +35,7 @@ dependencies { implementation 'io.quarkus:quarkus-kotlin' implementation 'io.quarkus:quarkus-resteasy' implementation 'io.quarkus:quarkus-resteasy-jackson' + implementation 'io.quarkus:quarkus-smallrye-openapi' api project(":EpcQrCode") diff --git a/EpcQrCodeRest/src/main/kotlin/net/codinux/banking/epcqrcode/rest/EpcQrCodeResource.kt b/EpcQrCodeRest/src/main/kotlin/net/codinux/banking/epcqrcode/rest/EpcQrCodeResource.kt index 8558183..4e261b9 100644 --- a/EpcQrCodeRest/src/main/kotlin/net/codinux/banking/epcqrcode/rest/EpcQrCodeResource.kt +++ b/EpcQrCodeRest/src/main/kotlin/net/codinux/banking/epcqrcode/rest/EpcQrCodeResource.kt @@ -4,6 +4,12 @@ import net.codinux.banking.epcqrcode.EpcQrCodeConfig import net.codinux.banking.epcqrcode.EpcQrCodeGenerator import net.codinux.banking.epcqrcode.rest.dto.GenerateEpcQrCodeRequestDto import net.codinux.banking.epcqrcode.rest.dto.GenerateEpcQrCodeResponseDto +import org.eclipse.microprofile.openapi.annotations.Operation +import org.eclipse.microprofile.openapi.annotations.media.Content +import org.eclipse.microprofile.openapi.annotations.media.Schema +import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody +import org.eclipse.microprofile.openapi.annotations.responses.APIResponse +import org.eclipse.microprofile.openapi.annotations.tags.Tag import org.slf4j.LoggerFactory import javax.ws.rs.* import javax.ws.rs.core.MediaType @@ -11,6 +17,8 @@ import javax.ws.rs.core.Response @Path("/epcqrcode/v1") +@Produces(MediaType.APPLICATION_JSON) +@Tag(name = "EPC QR Code") class EpcQrCodeResource { companion object { @@ -21,15 +29,25 @@ class EpcQrCodeResource { protected val epcQrCodeGenerator = EpcQrCodeGenerator() + @Operation(summary = "Creates a EPC QR code (also marketed as GiroCode, scan2Code, ...)") + @APIResponse(responseCode = "200", description = "The generated EPC QR Code", + content = [ Content(mediaType = "application/json", schema = Schema(implementation = GenerateEpcQrCodeResponseDto::class)) ]) + @APIResponse(responseCode = "500", description = "An internal error occurred") @GET - @Produces(MediaType.APPLICATION_JSON) fun createEpcQrCodeGet(@BeanParam request: GenerateEpcQrCodeRequestDto): Response { return handleJsonRequest(request) } + @Operation(summary = "Creates a EPC QR code (also marketed as GiroCode, scan2Code, ...)") + @APIResponse(responseCode = "200", description = "The generated EPC QR Code", + content = [ Content(mediaType = "application/json", schema = Schema(implementation = GenerateEpcQrCodeResponseDto::class)) ]) + @APIResponse(responseCode = "500", description = "An internal error occurred") @POST - @Produces(MediaType.APPLICATION_JSON) - fun createEpcQrCodePost(request: GenerateEpcQrCodeRequestDto): Response { + @Consumes(MediaType.APPLICATION_JSON) + fun createEpcQrCodePost( + @RequestBody(content = [ Content(schema = Schema(implementation = GenerateEpcQrCodeRequestDto::class)) ]) + request: GenerateEpcQrCodeRequestDto + ): Response { return handleJsonRequest(request) } diff --git a/EpcQrCodeRest/src/main/kotlin/net/codinux/banking/epcqrcode/rest/dto/GenerateEpcQrCodeRequestDto.kt b/EpcQrCodeRest/src/main/kotlin/net/codinux/banking/epcqrcode/rest/dto/GenerateEpcQrCodeRequestDto.kt index 10b7197..d776e23 100644 --- a/EpcQrCodeRest/src/main/kotlin/net/codinux/banking/epcqrcode/rest/dto/GenerateEpcQrCodeRequestDto.kt +++ b/EpcQrCodeRest/src/main/kotlin/net/codinux/banking/epcqrcode/rest/dto/GenerateEpcQrCodeRequestDto.kt @@ -3,6 +3,8 @@ package net.codinux.banking.epcqrcode.rest.dto import net.codinux.banking.epcqrcode.EpcQrCode import net.codinux.banking.epcqrcode.EpcQrCodeCharacterSet import net.codinux.banking.epcqrcode.ImageFormat +import org.eclipse.microprofile.openapi.annotations.media.Schema +import org.eclipse.microprofile.openapi.annotations.parameters.Parameter import javax.ws.rs.DefaultValue import javax.ws.rs.QueryParam @@ -10,33 +12,51 @@ import javax.ws.rs.QueryParam class GenerateEpcQrCodeRequestDto { @QueryParam("receiverName") + @Parameter(description = "The name of the receiver of this money transfer (that is in most cases your name or your company's name)", required = true) + @Schema(description = "The name of the receiver of this money transfer (that is in most cases your name or your company's name)", required = true) var receiverName: String = "" - @QueryParam("bic") - var bic: String? = null - @QueryParam("iban") + @Parameter(description = "Receiver's IBAN", required = true) + @Schema(description = "Receiver's IBAN", required = true) var iban: String = "" + @QueryParam("bic") + @Parameter(description = "Receiver's BIC (optional, only required for transfers to foreign countries)", required = false) + @Schema(description = "Receiver's BIC (optional, only required for transfers to foreign countries)", required = false) + var bic: String? = null + @QueryParam("amount") + @Parameter(description = "The amount to transfer (by standard optional, but highly recommended)", required = false) + @Schema(description = "The amount to transfer (by standard optional, but highly recommended)", required = false) var amount: String? = null @QueryParam("reference") + @Parameter(description = "The reference or usage of this money transfer", required = false) + @Schema(description = "The reference or usage of this money transfer", required = false) var reference: String? = null @QueryParam("noteToUser") + @Parameter(description = "An optional note that should be displayed to user (not implemented by all decoding applications)", required = false) + @Schema(description = "An optional note that should be displayed to user (not implemented by all decoding applications)", required = false) var noteToUser: String? = null @DefaultValue("" + EpcQrCode.DefaultHeightAndWidth) @QueryParam("imageHeightAndWidth") + @Parameter(description = "Height and width of the returned QR code", required = false) + @Schema(description = "Height and width of the returned QR code", defaultValue = "" + EpcQrCode.DefaultHeightAndWidth, required = false) var imageHeightAndWidth: Int = EpcQrCode.DefaultHeightAndWidth @DefaultValue("PNG") @QueryParam("imageFormat") + @Parameter(description = "The format of the returned QR code image", required = false) + @Schema(description = "The format of the returned QR code image", defaultValue = "PNG", required = false) var imageFormat: ImageFormat = ImageFormat.PNG @DefaultValue("UTF_8") @QueryParam("encoding") + @Parameter(description = "The charset used for encoding", required = false) + @Schema(description = "The charset used for encoding", defaultValue = "UTF_8", required = false) var encoding: EpcQrCodeCharacterSet = EpcQrCodeCharacterSet.UTF_8 } \ No newline at end of file diff --git a/EpcQrCodeRest/src/main/kotlin/net/codinux/banking/epcqrcode/rest/dto/GenerateEpcQrCodeResponseDto.kt b/EpcQrCodeRest/src/main/kotlin/net/codinux/banking/epcqrcode/rest/dto/GenerateEpcQrCodeResponseDto.kt index 93e9eba..9e5021f 100644 --- a/EpcQrCodeRest/src/main/kotlin/net/codinux/banking/epcqrcode/rest/dto/GenerateEpcQrCodeResponseDto.kt +++ b/EpcQrCodeRest/src/main/kotlin/net/codinux/banking/epcqrcode/rest/dto/GenerateEpcQrCodeResponseDto.kt @@ -1,7 +1,10 @@ package net.codinux.banking.epcqrcode.rest.dto +import org.eclipse.microprofile.openapi.annotations.media.Schema + class GenerateEpcQrCodeResponseDto( // JAX-RS automatically encodes ByteArray to Base64 + @Schema(description = "The Base64 encoded generated EPC QR Code") val qrCodeBase64Encoded: ByteArray ) \ No newline at end of file diff --git a/EpcQrCodeRest/src/main/resources/application.properties b/EpcQrCodeRest/src/main/resources/application.properties index 3bbeb7e..9d6174a 100644 --- a/EpcQrCodeRest/src/main/resources/application.properties +++ b/EpcQrCodeRest/src/main/resources/application.properties @@ -1,10 +1,10 @@ -quarkus.http.cors=true - # HTTP port settings (for production and dev) quarkus.http.port=8080 %dev.quarkus.http.port=6543 +quarkus.http.cors=true + # disable this output: # Press [h] for more options> @@ -17,6 +17,24 @@ quarkus.console.disable-input=true # Quarkus Native settings - quarkus.native.enable-https-url-handler=true -quarkus.native.enable-all-security-services=true \ No newline at end of file +quarkus.native.enable-all-security-services=true + + + +# so that on server endpoints like /openapi, /swagger-ui, /health can be reached under /epcqrcode (under /q/ it's not reachable on server) +quarkus.http.non-application-root-path=/epcqrcode + + +# OpenAPI and Swagger-UI + +quarkus.swagger-ui.always-include=true +quarkus.swagger-ui.theme=flattop +quarkus.swagger-ui.display-request-duration=true + +quarkus.smallrye-openapi.info-title=EPC QR Code REST API +quarkus.smallrye-openapi.info-version=1.0.0 +quarkus.smallrye-openapi.info-description=REST API to generate EPC QR codes (also marketed as GiroCode, scan2Code, ...) +quarkus.smallrye-openapi.info-contact-email=dev@codinux.net +quarkus.smallrye-openapi.info-contact-name=codinux GmbH & Co. KG +quarkus.smallrye-openapi.info-contact-url=https://codinux.net/ \ No newline at end of file