Merge pull request #6 from netz39/OAS3

📝 Complete OAS3

README.md

@@ -45,6 +45,9 @@ On return code `504` the call should be retried at a later point. In any other c
 Please note that the gateway send any valid JSON message to the AMQP queue. 
 Idempotency is not considered by the gateway in the sense that an already sent timestamp will not be suppressed.
 
+An [OAS3 schema ](https://swagger.io/specification/) can be obtained under the  
+URL `/swagger/power-meter-pulse-gateway-0.1.yml`.
+
 ### AMQP / RabbitMQ
 
 A pulse message that is received on the REST endpoint is sent to an AMQP queue with the routing key `PULSE_BINDING` on 

src/main/java/de/netz39/svc/pwrMtrPlsGw/PulseEndpoint.java

@@ -11,6 +11,8 @@
 import io.micronaut.http.annotation.Header;
 import io.micronaut.http.annotation.Post;
 import io.micronaut.rabbitmq.exception.RabbitClientException;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.responses.ApiResponse;
 import jakarta.inject.Inject;
 import org.slf4j.Logger;
@@ -36,10 +38,12 @@ public class PulseEndpoint {
 
 
     @Post
+    @Operation(summary = "Send a pulse message")
     @ApiResponse(responseCode = "201", description = "AMQP call successful")
     @ApiResponse(responseCode = "400", description = "Invalid call arguments")
-    @ApiResponse(responseCode = "504", description = "Timeout or error while connecting to RabbitMQ, please retry!")
+    @ApiResponse(responseCode = "504", description = "Timeout or error while connecting to RabbitMQ, please retry later!")
     public HttpStatus pulse(@Body PulseMessage body,
+                            @Parameter(description = "Authorization string as `Beaker <token>`, see README for details")
                             @Header(HttpHeaders.AUTHORIZATION) @Nullable String authorization) {
         // Check Authorization if configured
         if (! isValidAuth(authorization)) {

src/main/java/de/netz39/svc/pwrMtrPlsGw/PulseMessage.java

@@ -3,6 +3,7 @@
 import com.fasterxml.jackson.annotation.JsonFormat;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import io.micronaut.context.annotation.Bean;
+import io.swagger.v3.oas.annotations.media.Schema;
 import net.jcip.annotations.Immutable;
 
 import java.time.Instant;
@@ -17,6 +18,7 @@
  *     }
  * </code>
  */
+@Schema(description = "Message encoding the timestamp of a power meter pulse")
 @Immutable
 @Bean
 public class PulseMessage {
@@ -26,6 +28,7 @@ static PulseMessage withTimestamp(final Instant timestamp) {
 
     @JsonProperty("timestamp")
     @JsonFormat(shape = JsonFormat.Shape.STRING)
+    @Schema(description = "Timestamp in ISO 8601 form")
     private final Instant timestamp;
 
     PulseMessage(@JsonProperty(value="timestamp", required = true) Instant timestamp) {

src/main/resources/application.yml

@@ -9,7 +9,7 @@ micronaut:
     static-resources:
       swagger:
         paths: classpath:META-INF/swagger
-        mapping: /oas3/**
+        mapping: /swagger/**
 netty:
   default:
     allocator: