Added OpenAPI / Swagger documentation

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")
 

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)
     }
 

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
 
 }

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
 )

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
+
+
+
+# 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/