From 5a4fe49f501a0afe1a4316a8b0a725c1f1fbcd33 Mon Sep 17 00:00:00 2001 From: Stefan Haun Date: Fri, 26 Aug 2022 17:55:01 +0200 Subject: [PATCH 1/3] :memo: Update OAS3 documentation for bean and endpoint --- src/main/java/de/netz39/svc/pwrMtrPlsGw/PulseEndpoint.java | 6 +++++- src/main/java/de/netz39/svc/pwrMtrPlsGw/PulseMessage.java | 3 +++ 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/src/main/java/de/netz39/svc/pwrMtrPlsGw/PulseEndpoint.java b/src/main/java/de/netz39/svc/pwrMtrPlsGw/PulseEndpoint.java index e3b523e..6586190 100644 --- a/src/main/java/de/netz39/svc/pwrMtrPlsGw/PulseEndpoint.java +++ b/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 `, see README for details") @Header(HttpHeaders.AUTHORIZATION) @Nullable String authorization) { // Check Authorization if configured if (! isValidAuth(authorization)) { diff --git a/src/main/java/de/netz39/svc/pwrMtrPlsGw/PulseMessage.java b/src/main/java/de/netz39/svc/pwrMtrPlsGw/PulseMessage.java index 8c6ef84..3b75c9c 100644 --- a/src/main/java/de/netz39/svc/pwrMtrPlsGw/PulseMessage.java +++ b/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 @@ * } * */ +@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) { From 337fa7e1911e5e67e691811f7315710f08bd3b01 Mon Sep 17 00:00:00 2001 From: Stefan Haun Date: Fri, 26 Aug 2022 17:55:21 +0200 Subject: [PATCH 2/3] :wrench: Fix mapping for the OAS3 URL --- src/main/resources/application.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/main/resources/application.yml b/src/main/resources/application.yml index 30b0a44..f1ab288 100644 --- a/src/main/resources/application.yml +++ b/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: From 8c338bfef4ea90002927aaf1408de14cfa8739c8 Mon Sep 17 00:00:00 2001 From: Stefan Haun Date: Fri, 26 Aug 2022 17:55:49 +0200 Subject: [PATCH 3/3] :memo: Mention OAS3 URL in README --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 579c63c..78c38dc 100644 --- a/README.md +++ b/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