chore(api): add OAS annotations, add required config

eclipse-tractusx · Mar 21, 2024 · 33e3346 · 33e3346
1 parent 3385f2c
commit 33e3346
Show file tree

Hide file tree

Showing 7 changed files with 120 additions and 7 deletions.
diff --git a/.github/workflows/publish-openapi.yaml b/.github/workflows/publish-openapi.yaml
@@ -5,6 +5,10 @@ on:
     branches:
       - main
 
+permissions:
+  contents: read
+  pages: write # required for openapi publishing
+
 jobs:
   publish:
     uses: eclipse-edc/.github/.github/workflows/publish-openapi-ui.yml@main

diff --git a/api/directory-api/src/main/java/org/eclipse/tractusx/bdrs/api/directory/DirectoryApi.java b/api/directory-api/src/main/java/org/eclipse/tractusx/bdrs/api/directory/DirectoryApi.java
@@ -1,7 +1,31 @@
 package org.eclipse.tractusx.bdrs.api.directory;
 
+import io.swagger.v3.oas.annotations.OpenAPIDefinition;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.ws.rs.core.Response;
+import org.eclipse.edc.web.spi.ApiErrorDetail;
+
 /**
  * Provides the public BPN Directory API.
  */
+@OpenAPIDefinition
+@Tag(name = "BDRS Server Directory API")
 public interface DirectoryApi {
+    @Operation(description = "Gets a binary gzipped stream with BPN/DID mapping entries.",
+            responses = {
+                    @ApiResponse(responseCode = "200", description = "The GZipped binary stream contains BPN-to-DID mapping entries."),
+                    @ApiResponse(responseCode = "400", description = "Request body was malformed",
+                            content = @Content(array = @ArraySchema(schema = @Schema(implementation = ApiErrorDetail.class)))),
+                    @ApiResponse(responseCode = "401", description = "User is not authenticated",
+                            content = @Content(array = @ArraySchema(schema = @Schema(implementation = ApiErrorDetail.class)))),
+                    @ApiResponse(responseCode = "403", description = "User is not authorized to obtain BPN/DID mapping data",
+                            content = @Content(array = @ArraySchema(schema = @Schema(implementation = ApiErrorDetail.class))))
+
+            })
+    Response getData();
 }
diff --git a/...ory-api/src/main/java/org/eclipse/tractusx/bdrs/api/directory/DirectoryApiController.java b/...ory-api/src/main/java/org/eclipse/tractusx/bdrs/api/directory/DirectoryApiController.java
@@ -21,21 +21,22 @@
 import jakarta.ws.rs.core.StreamingOutput;
 import org.eclipse.tractusx.bdrs.spi.store.DidEntryStore;
 
-import static jakarta.ws.rs.core.MediaType.APPLICATION_JSON;
+import static jakarta.ws.rs.core.MediaType.APPLICATION_OCTET_STREAM;
 import static jakarta.ws.rs.core.Response.ok;
 
 /**
  * Implements the BPN Directory API. The BPN Directory is returned in compressed (GZIP) form.
  */
 @Path("/")
-@Produces(APPLICATION_JSON)
+@Produces(APPLICATION_OCTET_STREAM)
 public class DirectoryApiController implements DirectoryApi {
     private final DidEntryStore store;
 
     public DirectoryApiController(DidEntryStore store) {
         this.store = store;
     }
 
+    @Override
     @Path("/bpn-directory")
     @GET
     public Response getData() {

diff --git a/...tory-api/src/main/java/org/eclipse/tractusx/bdrs/api/directory/DirectoryApiExtension.java b/...tory-api/src/main/java/org/eclipse/tractusx/bdrs/api/directory/DirectoryApiExtension.java
@@ -14,7 +14,6 @@
 
 package org.eclipse.tractusx.bdrs.api.directory;
 
-import org.eclipse.edc.runtime.metamodel.annotation.BaseExtension;
 import org.eclipse.edc.runtime.metamodel.annotation.Extension;
 import org.eclipse.edc.runtime.metamodel.annotation.Inject;
 import org.eclipse.edc.spi.system.ServiceExtension;
@@ -27,7 +26,6 @@
 /**
  * Loads resources for the BPN Directory API.
  */
-@BaseExtension
 @Extension(NAME)
 public class DirectoryApiExtension implements ServiceExtension {
     public static final String NAME = "BPN Directory API";

diff --git a/api/management-api/src/main/java/org/eclipse/tractusx/bdrs/api/management/ManagementApi.java b/api/management-api/src/main/java/org/eclipse/tractusx/bdrs/api/management/ManagementApi.java
@@ -14,8 +14,80 @@
 
 package org.eclipse.tractusx.bdrs.api.management;
 
+import io.swagger.v3.oas.annotations.OpenAPIDefinition;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.parameters.RequestBody;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.ws.rs.PathParam;
+import jakarta.ws.rs.core.Response;
+import org.eclipse.edc.web.spi.ApiErrorDetail;
+
 /**
  * Exposes the BDRS management API. Note that this API should not be exposed over a public network.
  */
+@OpenAPIDefinition
+@Tag(name = "BDRS Server Management API")
 public interface ManagementApi {
+    @Operation(description = "Gets a binary gzipped stream with BPN/DID mapping entries.",
+            responses = {
+                    @ApiResponse(responseCode = "200", description = "The GZipped binary stream contains BPN-to-DID mapping entries."),
+                    @ApiResponse(responseCode = "400", description = "Request body was malformed",
+                            content = @Content(array = @ArraySchema(schema = @Schema(implementation = ApiErrorDetail.class)))),
+                    @ApiResponse(responseCode = "401", description = "User is not authenticated",
+                            content = @Content(array = @ArraySchema(schema = @Schema(implementation = ApiErrorDetail.class)))),
+                    @ApiResponse(responseCode = "403", description = "User is not authorized to obtain BPN/DID mapping data",
+                            content = @Content(array = @ArraySchema(schema = @Schema(implementation = ApiErrorDetail.class))))
+
+            })
+    Response getData();
+
+    @Operation(description = "Creates a new BpnMapping entry, or updates an existing one.",
+            requestBody = @RequestBody(
+                    content = @Content(schema = @Schema(implementation = BpnMapping.class))
+            ),
+            responses = {
+                    @ApiResponse(responseCode = "204", description = "BPN/DID mapping entry successfully created (updated)."),
+                    @ApiResponse(responseCode = "400", description = "Request body was malformed",
+                            content = @Content(array = @ArraySchema(schema = @Schema(implementation = ApiErrorDetail.class)))),
+                    @ApiResponse(responseCode = "401", description = "User is not authenticated",
+                            content = @Content(array = @ArraySchema(schema = @Schema(implementation = ApiErrorDetail.class)))),
+                    @ApiResponse(responseCode = "403", description = "User is not authorized to create BPN/DID mapping data",
+                            content = @Content(array = @ArraySchema(schema = @Schema(implementation = ApiErrorDetail.class))))
+            })
+    void save(BpnMapping mapping);
+
+    @Operation(description = "Updates a BpnMapping entry",
+            requestBody = @RequestBody(
+                    content = @Content(schema = @Schema(implementation = BpnMapping.class))
+            ),
+            responses = {
+                    @ApiResponse(responseCode = "204", description = "BPN/DID mapping entry successfully created"),
+                    @ApiResponse(responseCode = "400", description = "Request body was malformed",
+                            content = @Content(array = @ArraySchema(schema = @Schema(implementation = ApiErrorDetail.class)))),
+                    @ApiResponse(responseCode = "401", description = "User is not authenticated",
+                            content = @Content(array = @ArraySchema(schema = @Schema(implementation = ApiErrorDetail.class)))),
+                    @ApiResponse(responseCode = "403", description = "User is not authorized to update BPN/DID mapping data",
+                            content = @Content(array = @ArraySchema(schema = @Schema(implementation = ApiErrorDetail.class)))),
+                    @ApiResponse(responseCode = "404", description = "No mapping for that BPN was registered",
+                            content = @Content(array = @ArraySchema(schema = @Schema(implementation = ApiErrorDetail.class)))),
+            })
+    void update(BpnMapping mapping);
+
+    @Operation(description = "Removes a BpnMapping entry for the given BPN",
+            responses = {
+                    @ApiResponse(responseCode = "204", description = "BpnMapping entry was deleted successfully"),
+                    @ApiResponse(responseCode = "400", description = "Request body was malformed",
+                            content = @Content(array = @ArraySchema(schema = @Schema(implementation = ApiErrorDetail.class)))),
+                    @ApiResponse(responseCode = "401", description = "User is not authenticated",
+                            content = @Content(array = @ArraySchema(schema = @Schema(implementation = ApiErrorDetail.class)))),
+                    @ApiResponse(responseCode = "403", description = "User is not authorized to delete BPN/DID mapping data",
+                            content = @Content(array = @ArraySchema(schema = @Schema(implementation = ApiErrorDetail.class)))),
+                    @ApiResponse(responseCode = "404", description = "No mapping for that BPN was registered",
+                            content = @Content(array = @ArraySchema(schema = @Schema(implementation = ApiErrorDetail.class)))),
+            })
+    void delete(@PathParam("bpn") String bpn);
 }
diff --git a/...t-api/src/main/java/org/eclipse/tractusx/bdrs/api/management/ManagementApiController.java b/...t-api/src/main/java/org/eclipse/tractusx/bdrs/api/management/ManagementApiController.java
@@ -41,6 +41,7 @@ public ManagementApiController(DidEntryStore store) {
         this.store = store;
     }
 
+    @Override
     @Path("/bpn-directory")
     @GET
     public Response getData() {
@@ -49,18 +50,21 @@ public Response getData() {
                 .build();
     }
 
+    @Override
     @Path("/bpn-directory")
     @POST
     public void save(BpnMapping mapping) {
         store.save(new DidEntry(mapping.bpn(), mapping.did()));
     }
 
+    @Override
     @Path("/bpn-directory")
     @PUT
     public void update(BpnMapping mapping) {
         store.update(new DidEntry(mapping.bpn(), mapping.did()));
     }
 
+    @Override
     @Path("/bpn-directory/{bpn}")
     @DELETE
     public void delete(@PathParam("bpn") String bpn) {

diff --git a/build.gradle.kts b/build.gradle.kts
@@ -52,6 +52,16 @@ allprojects {
             // override default dependency versions here
             metaModel.set(metaModelVersion)
         }
+        swagger {
+            title.set((project.findProperty("apiTitle") ?: "Tractus-X BDRS Server REST API") as String)
+            description =
+                (project.findProperty("apiDescription")
+                    ?: "Tractus-X REST APIs - merged by OpenApiMerger") as String
+            outputFilename.set(project.name)
+            outputDirectory.set(file("${rootProject.projectDir.path}/resources/openapi/yaml"))
+            resourcePackages = setOf("org.eclipse.tractusx.bdrs")
+        }
+
     }
 
     // EdcRuntimeExtension uses this to determine the runtime classpath of the module to run.
@@ -65,7 +75,7 @@ allprojects {
 subprojects {
     afterEvaluate {
         if (project.plugins.hasPlugin("com.github.johnrengelman.shadow") &&
-                file("${project.projectDir}/src/main/docker/Dockerfile").exists()
+            file("${project.projectDir}/src/main/docker/Dockerfile").exists()
         ) {
 
             // this task copies some legal docs into the build folder, so we can easily copy them into the docker images
@@ -100,8 +110,8 @@ subprojects {
             }
             // make sure  always runs after "dockerize" and after "copyOtel"
             dockerTask
-                    .dependsOn(tasks.named(ShadowJavaPlugin.SHADOW_JAR_TASK_NAME))
-                    .dependsOn(copyLegalDocs)
+                .dependsOn(tasks.named(ShadowJavaPlugin.SHADOW_JAR_TASK_NAME))
+                .dependsOn(copyLegalDocs)
         }
     }
 }