Feat: Add OpenAPI descriptions for Gate

bpdm-bridge-dummy/src/main/kotlin/com/catenax/bpdm/bridge/dummy/dto/GateLegalEntityInfo.kt

@@ -23,7 +23,7 @@ import org.eclipse.tractusx.bpdm.common.dto.LegalEntityDto
 import org.eclipse.tractusx.bpdm.gate.api.model.response.AddressGateInputDto
 
 data class GateLegalEntityInfo(
-    val legalNameParts: List<String>,
+    val legalNameParts: Collection<String>,
     val legalEntity: LegalEntityDto,
     val legalAddress: AddressGateInputDto,
     val externalId: String,

bpdm-bridge-dummy/src/main/kotlin/com/catenax/bpdm/bridge/dummy/service/GateUpdateService.kt

@@ -270,7 +270,7 @@ class GateUpdateService(
 
     private fun putAddressOutput(request: AddressGateOutputRequest?) =
         request?.let {
-            gateClient.addresses().putAddressesOutput(listOf(it))
+            gateClient.addresses().upsertAddressesOutput(listOf(it))
         }
 
     private fun upsertSharingState(request: SharingStateDto?) =

bpdm-common/src/main/kotlin/org/eclipse/tractusx/bpdm/common/dto/openapidescription/ChangelogDescription.kt

@@ -27,4 +27,5 @@ object ChangelogDescription {
     const val timestamp = "The date and time when the changelog entry was created."
     const val businessPartnerType = "One of the types of business partners for which the changelog entry was created: legal entity, site, address."
     const val bpn = "The business partner number for which the changelog entry was created. Can be either a BPNL, BPNS or BPNA."
+    const val externalId = "The external identifier of the business partner for which the changelog entry was created."
 }

bpdm-common/src/main/kotlin/org/eclipse/tractusx/bpdm/common/dto/openapidescription/CommonDescription.kt

@@ -20,11 +20,13 @@
 package org.eclipse.tractusx.bpdm.common.dto.openapidescription
 
 object CommonDescription {
+    const val headerEntityWithErrorsWrapper = "Holds information about successfully and failed entities after the creating/updating of several objects"
+
     const val createdAt = "The date when the data record has been created."
     const val updatedAt = "The date when the data record has been last updated."
 
     const val index = "User defined index to conveniently match this entry to the corresponding entry in the response."
     const val score = "Relative quality score of the match. The higher the better."
 
-    const val entityWithErrorsWrapperHeader = "Holds information about successfully and failed entities after the creating/updating of several objects"
+    const val externalId = "The identifier which uniquely identifies (in the internal system landscape of the sharing member) the business partner."
 }

bpdm-common/src/main/kotlin/org/eclipse/tractusx/bpdm/common/dto/openapidescription/LegalEntityDescription.kt

@@ -33,14 +33,16 @@ object LegalEntityDescription {
             "identified by the BPNL."
     const val headerCreateRequest = "Request for creating new business partner record of type legal entity. $header"
     const val headerUpdateRequest = "Request for updating a business partner record of type legal entity. $header"
-    const val headerCreateResponse = "Created business partner of type legal entity. $header"
+    const val headerUpsertRequest = "Request for creating/updating a business partner record of type legal entity. $header"
+    const val headerUpsertResponse = "Created/updated business partner of type legal entity. $header"
     const val headerMatchResponse = "Match with score for a business partner record of type legal entity. $header"
 
     const val bpnl = "A BPNL represents and uniquely identifies a legal entity, which is defined by its legal name (including legal form, if registered), " +
             "legal address and tax number."
     const val currentness = "The date the business partner data was last indicated to be still current."
 
     const val legalName = "The name of the legal entity according to official registers."
+    const val legalNameParts = "The list of name parts of the legal entity to accommodate the different number of name fields in different systems."
     const val legalShortName = "The abbreviated name of the legal entity."
     const val legalForm = "The legal form of the legal entity."
     const val legalAddress = "The official, legal correspondence address to be provided to government and tax authorities " +
@@ -50,4 +52,5 @@ object LegalEntityDescription {
     const val states = "The list of (temporary) states of the legal entity."
     const val classifications = "The list of classifications of the legal entity, such as a specific industry."
     const val relations = "Relations to other business partners."
+    const val roles = "Roles this business partner takes in relation to the sharing member."
 }

bpdm-common/src/main/kotlin/org/eclipse/tractusx/bpdm/common/dto/openapidescription/LogisticAddressDescription.kt

@@ -32,6 +32,7 @@ object LogisticAddressDescription {
             "uniquely identified by the BPNA."
     const val headerCreateRequest = "Request for creating new business partner record of type address. $header"
     const val headerUpdateRequest = "Request for updating a business partner record of type address. $header"
+    const val headerUpsertRequest = "Request for creating/updating a business partner record of type address. $header"
     const val headerCreateResponse = "Created business partner of type address. $header"
     const val headerMatchResponse = "Match for a business partner record of type address. $header"
 
@@ -40,6 +41,8 @@ object LogisticAddressDescription {
             "It is important to note that only the BPNL must be used to uniquely identify a legal entity. " +
             "Even in the case that the BPNA represents the legal address of the legal entity, it shall not be used to uniquely identify the legal entity."
     const val name = "The name of the address. This is not according to official registers but according to the name the sharing member chooses."
+    const val nameParts = "The list of name parts of the address to accommodate the different number of name fields in different systems. " +
+            "This is not according to official registers but according to the name the sharing member chooses."
     const val states = "The list of (temporary) states of the address."
     const val identifiers = "The list of identifiers of the address."
     const val physicalPostalAddress = "The physical postal address of the address, such as an office, warehouse, gate, etc."
@@ -49,7 +52,12 @@ object LogisticAddressDescription {
     const val bpnSite = "The BPNS of the site the address belongs to."
     const val isMainAddress = "Indicates if the address is the main address to a site. " +
             "This is where typically the main entrance or the reception is located, or where the mail is delivered to."
+    const val roles = "Roles this business partner takes in relation to the sharing member."
 
     const val bpnParent = "BPNL of the legal entity or BPNS of the site this address belongs to."
+    const val legalEntityExternalId = "The identifier which uniquely identifies (in the internal system landscape of the sharing member) " +
+            "the business partner, representing the legal entity, that owns the address."
+    const val siteExternalId = "The identifier which uniquely identifies (in the internal system landscape of the sharing member) " +
+            "the business partner, representing the site, that the address belongs to."
     const val address = "Address information"
 }

bpdm-common/src/main/kotlin/org/eclipse/tractusx/bpdm/common/dto/openapidescription/SiteDescription.kt

@@ -31,16 +31,22 @@ object SiteDescription {
             "addresses belong to which site. A site is uniquely identified by the BPNS."
     const val headerCreateRequest = "Request for creating new business partner record of type site. $header"
     const val headerUpdateRequest = "Request for updating a business partner record of type site. $header"
-    const val headerCreateResponse = "Created business partner of type site. $header"
+    const val headerUpsertRequest = "Request for creating/updating a business partner record of type site. $header"
+    const val headerUpsertResponse = "Created/updated business partner of type site. $header"
     const val headerMatchResponse = "Match for a business partner record of type site. $header"
 
     const val bpns = "A BPNS represents and uniquely identifies a site, which is where for example a production plant, " +
             "a warehouse, or an office building is located."
     const val name = "The name of the site. This is not according to official registers but according to the name the owner chooses."
+    const val nameParts = "The list of name parts of the site to accommodate the different number of name fields in different systems. " +
+            "This is not according to official registers but according to the name the owner chooses."
     const val states = "The list of the (temporary) states of the site."
     const val bpnLegalEntity = "The BPNL of the legal entity owning the site."
     const val mainAddress = "The address, where typically the main entrance or the reception is located, or where the mail is delivered to."
+    const val roles = "Roles this business partner takes in relation to the sharing member."
 
     const val bpnlParent = "The BPNL of the legal entity owning the site."
+    const val legalEntityExternalId = "The identifier which uniquely identifies (in the internal system landscape of the sharing member) " +
+            "the business partner owning the site."
     const val site = "Site information"
 }

bpdm-common/src/main/kotlin/org/eclipse/tractusx/bpdm/common/dto/openapidescription/StreetDescription.kt

@@ -27,4 +27,9 @@ object StreetDescription {
     const val milestone = "The number representing the exact location of an addressed object within a street without house numbers, such as within long roads."
     const val direction = "The cardinal direction describing where the exit to the location of the addressed object on large highways / " +
             "motorways is located, such as Highway 101 South."
+
+    const val namePrefix = "The street related information, which is usually printed before the official street name on an address label."
+    const val additionalNamePrefix = "The additional street related information, which is usually printed before the official street name on an address label."
+    const val nameSuffix = "The street related information, which is usually printed after the official street name on an address label."
+    const val additionalNameSuffix = "The additional street related information, which is usually printed after the official street name on an address label."
 }

bpdm-gate-api/src/main/kotlin/org/eclipse/tractusx/bpdm/gate/api/GateAddressApi.kt

@@ -44,12 +44,11 @@ import org.springframework.web.service.annotation.PutExchange
 @HttpExchange("/api/catena")
 interface GateAddressApi {
 
-
     @Operation(
-        summary = "Create or update addresses.",
+        summary = "Creates or updates an existing address in the input stage",
         description = "Create or update addresses. " +
-                "Updates instead of creating a new address if an already existing external id is used. " +
-                "The same external id may not occur more than once in a single request. " +
+                "Updates instead of creating a new address if an already existing external ID is used. " +
+                "The same external ID may not occur more than once in a single request. " +
                 "For a single request, the maximum number of addresses in the request is limited to \${bpdm.api.upsert-limit} entries."
     )
     @ApiResponses(
@@ -62,25 +61,23 @@ interface GateAddressApi {
     @PutExchange("/input/addresses")
     fun upsertAddresses(@RequestBody addresses: Collection<AddressGateInputRequest>): ResponseEntity<Unit>
 
-
     @Operation(
-        summary = "Get address by external identifier",
-        description = "Get address by external identifier."
+        summary = "Returns address by external ID from the input stage",
+        description = "Returns address by external ID from the input stage."
     )
     @ApiResponses(
         value = [
-            ApiResponse(responseCode = "200", description = "Found address with external identifier"),
-            ApiResponse(responseCode = "404", description = "No address found under specified external identifier", content = [Content()])
+            ApiResponse(responseCode = "200", description = "Found address with external ID"),
+            ApiResponse(responseCode = "404", description = "No address found under specified external ID", content = [Content()])
         ]
     )
-
     @GetMapping("/input/addresses/{externalId}")
     @GetExchange("/input/addresses/{externalId}")
-    fun getAddressByExternalId(@Parameter(description = "External identifier") @PathVariable externalId: String): AddressGateInputDto
+    fun getAddressByExternalId(@Parameter(description = "External ID") @PathVariable externalId: String): AddressGateInputDto
 
     @Operation(
-        summary = "Get page of addresses filtered by a collection of externalIds",
-        description = "Get page of addresses filtered by a collection of externalIds."
+        summary = "Returns addresses by an array of external IDs from the input stage",
+        description = "Returns page of addresses from the input stage. Can optionally be filtered by external IDs."
     )
     @ApiResponses(
         value = [
@@ -95,10 +92,9 @@ interface GateAddressApi {
         @RequestBody externalIds: Collection<String>
     ): PageDto<AddressGateInputDto>
 
-
     @Operation(
-        summary = "Get page of addresses",
-        description = "Get page of addresses."
+        summary = "Returns addresses from the input stage",
+        description = "Returns page of addresses from the input stage."
     )
     @ApiResponses(
         value = [
@@ -111,8 +107,8 @@ interface GateAddressApi {
     fun getAddresses(@ParameterObject @Valid paginationRequest: PaginationRequest): PageDto<AddressGateInputDto>
 
     @Operation(
-        summary = "Get page of addresses (Output)",
-        description = "Get page of addresses (Output). Can optionally be filtered by external ids."
+        summary = "Returns addresses by an array of external IDs from the output stage",
+        description = "Get page of addresses from the output stage. Can optionally be filtered by external IDs."
     )
     @ApiResponses(
         value = [
@@ -128,10 +124,10 @@ interface GateAddressApi {
     ): PageDto<AddressGateOutputDto>
 
     @Operation(
-        summary = "Create or update output addresses.",
+        summary = "Creates or updates an existing address in the output stage",
         description = "Create or update addresses (Output). " +
-                "Updates instead of creating a new address if an already existing external id is used. " +
-                "The same external id may not occur more than once in a single request. " +
+                "Updates instead of creating a new address if an already existing external ID is used. " +
+                "The same external ID may not occur more than once in a single request. " +
                 "For a single request, the maximum number of addresses in the request is limited to \${bpdm.api.upsert-limit} entries."
 
     )
@@ -143,6 +139,5 @@ interface GateAddressApi {
     )
     @PutMapping("/output/addresses")
     @PutExchange("/output/addresses")
-    fun putAddressesOutput(@RequestBody addresses: Collection<AddressGateOutputRequest>): ResponseEntity<Unit>
-
-}
+    fun upsertAddressesOutput(@RequestBody addresses: Collection<AddressGateOutputRequest>): ResponseEntity<Unit>
+}

bpdm-gate-api/src/main/kotlin/org/eclipse/tractusx/bpdm/gate/api/GateChangelogApi.kt

@@ -38,10 +38,10 @@ import org.springframework.web.service.annotation.PostExchange
 @HttpExchange("/api/catena")
 interface GateChangelogApi {
 
-
     @Operation(
-        summary = "Get business partner changelog entries for changes to the business partner input data",
-        description = "Get business partner changelog entries for changes to the business partner input data. Filter by list external id, from timestamp and/or lsa type"
+        summary = "Returns changelog entries for changes to the business partner input stage",
+        description = "Returns changelog entries as of a specified timestamp from the input stage, " +
+                "optionally filtered by timestamp, an array of external IDs and a business partner type."
     )
     @ApiResponses(
         value = [
@@ -56,10 +56,10 @@ interface GateChangelogApi {
         @RequestBody searchRequest: ChangelogSearchRequest
     ): PageChangeLogDto<ChangelogGateDto>
 
-
     @Operation(
-        summary = "Get business partner changelog entries for changes to the business partner output data",
-        description = "Get business partner changelog entries for changes to the business partner output data. Filter by list external id, from timestamp and/or lsa type"
+        summary = "Returns changelog entries for changes to the business partner output stage",
+        description = "Returns changelog entries as of a specified timestamp from the output stage, " +
+                "optionally filtered by timestamp, an array of external IDs and a business partner type."
     )
     @ApiResponses(
         value = [
@@ -73,4 +73,4 @@ interface GateChangelogApi {
         @ParameterObject @Valid paginationRequest: PaginationRequest,
         @RequestBody searchRequest: ChangelogSearchRequest
     ): PageChangeLogDto<ChangelogGateDto>
-}
+}