Merge pull request #688 from catenax-ng/doc/generic-lsa-parts

Doc: adjust openApi documentation for new generic business partner model to standard

bpdm-cleaning-service-dummy/src/main/kotlin/org/eclipse/tractusx/bpdm/cleaning/service/CleaningServiceDummy.kt

@@ -121,20 +121,20 @@ class CleaningServiceDummy(
 
         val legalAddress = addressPartner.copy(bpnAReference = legalAddressBpnReference)
 
-        val bpnReferenceDto = createBpnReference(genericPartner.legalEntity.bpnL)
+        val bpnReferenceDto = createBpnReference(genericPartner.legalEntity.legalEntityBpn)
 
         return genericPartner.toLegalEntityDto(bpnReferenceDto, legalAddress)
 
     }
 
     fun createAddressRepresentation(genericPartner: BusinessPartnerGenericDto): LogisticAddressDto {
-        val bpnReferenceDto = createBpnReference(genericPartner.address.bpnA)
+        val bpnReferenceDto = createBpnReference(genericPartner.address.addressBpn)
         return genericPartner.toLogisticAddressDto(bpnReferenceDto)
     }
 
     fun createSiteRepresentation(genericPartner: BusinessPartnerGenericDto, siteAddressReference: LogisticAddressDto): SiteDto {
         val legalName = genericPartner.nameParts.joinToString(" ")
-        val bpnReferenceDto = createBpnReference(genericPartner.site.bpnS)
+        val bpnReferenceDto = createBpnReference(genericPartner.site.siteBpn)
         return genericPartner.toSiteDto(bpnReferenceDto, legalName, siteAddressReference)
     }
 
@@ -152,7 +152,7 @@ class CleaningServiceDummy(
     fun shouldCreateSite(genericPartner: BusinessPartnerGenericDto): Boolean {
         return genericPartner.address.addressType == AddressType.SiteMainAddress ||
                 genericPartner.address.addressType == AddressType.LegalAndSiteMainAddress ||
-                genericPartner.site.bpnS != null
+                genericPartner.site.siteBpn != null
     }
 
 

bpdm-cleaning-service-dummy/src/test/kotlin/org/eclipse/tractusx/bpdm/cleaning/service/CleaningServiceDummyTest.kt

@@ -51,7 +51,7 @@ class CleaningServiceDummyTest @Autowired constructor(
 
         val result = cleaningServiceDummy.processCleaningTask(taskStepReservationEntryDto)
 
-        val expectedBpnA = taskStepReservationEntryDto.businessPartner.generic.address.bpnA
+        val expectedBpnA = taskStepReservationEntryDto.businessPartner.generic.address.addressBpn
 
         val resultedAddress = result.businessPartner?.address
 
@@ -112,9 +112,9 @@ class CleaningServiceDummyTest @Autowired constructor(
 
         val result = cleaningServiceDummy.processCleaningTask(taskStepReservationEntryDto)
 
-        val expectedBpnA = taskStepReservationEntryDto.businessPartner.generic.address.bpnA
+        val expectedBpnA = taskStepReservationEntryDto.businessPartner.generic.address.addressBpn
 
-        val expectedBpnL = taskStepReservationEntryDto.businessPartner.generic.legalEntity.bpnL
+        val expectedBpnL = taskStepReservationEntryDto.businessPartner.generic.legalEntity.legalEntityBpn
 
         val resultedAddress = result.businessPartner?.address
 
@@ -153,9 +153,9 @@ class CleaningServiceDummyTest @Autowired constructor(
 
         val resultedSite = result.businessPartner?.site
 
-        val expectedBpnA = taskStepReservationResponse.businessPartner.generic.address.bpnA
+        val expectedBpnA = taskStepReservationResponse.businessPartner.generic.address.addressBpn
 
-        val expectedBpnS = taskStepReservationResponse.businessPartner.generic.site.bpnS
+        val expectedBpnS = taskStepReservationResponse.businessPartner.generic.site.siteBpn
 
 
         // legalEntity should Generate new bpnL and legalAddress should use passed bpnA since address type is LegalAndSiteMainAddress

bpdm-cleaning-service-dummy/src/test/kotlin/org/eclipse/tractusx/bpdm/cleaning/testdata/CommonValues.kt

@@ -105,7 +105,7 @@ object CommonValues {
         states = states,
         roles = roles,
         ownerBpnL = "ownerBpnL2",
-        legalEntity = LegalEntityComponent(
+        legalEntity = LegalEntityRepresentation(
             shortName = shortName,
             legalForm = legalForm,
             classifications = classifications
@@ -116,7 +116,7 @@ object CommonValues {
     val businessPartnerWithBpnA = with(businessPartnerWithEmptyBpns) {
         copy(
             address = address.copy(
-                bpnA = "FixedBPNA",
+                addressBpn = "FixedBPNA",
                 addressType = postalAddressForAdditional.addressType,
                 physicalPostalAddress = postalAddressForAdditional.physicalPostalAddress,
                 alternativePostalAddress = postalAddressForAdditional.alternativePostalAddress
@@ -128,13 +128,13 @@ object CommonValues {
     val businessPartnerWithBpnLAndBpnAAndLegalAddressType = with(businessPartnerWithEmptyBpns) {
         copy(
             address = address.copy(
-                bpnA = "FixedBPNA",
+                addressBpn = "FixedBPNA",
                 addressType = postalAddressForLegal.addressType,
                 physicalPostalAddress = postalAddressForLegal.physicalPostalAddress,
                 alternativePostalAddress = postalAddressForLegal.alternativePostalAddress
             ),
             legalEntity = legalEntity.copy(
-                bpnL = "FixedBPNL"
+                legalEntityBpn = "FixedBPNL"
             )
         )
     }
@@ -152,13 +152,13 @@ object CommonValues {
     val businessPartnerWithBpnSAndBpnAAndLegalAndSiteMainAddressType = with(businessPartnerWithEmptyBpns) {
         copy(
             address = address.copy(
-                bpnA = "FixedBPNA",
+                addressBpn = "FixedBPNA",
                 addressType = postalAddressForLegalAndSite.addressType,
                 physicalPostalAddress = postalAddressForLegalAndSite.physicalPostalAddress,
                 alternativePostalAddress = postalAddressForLegalAndSite.alternativePostalAddress
             ),
             site = site.copy(
-                bpnS = "FixedBPNS"
+                siteBpn = "FixedBPNS"
             )
         )
     }

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

@@ -33,40 +33,55 @@ interface IBaseBusinessPartnerDto {
     @get:ArraySchema(arraySchema = Schema(description = "The list of (temporary) states of the business partner. Sorted and duplicates removed by the service."))
     val states: Collection<IBusinessPartnerStateDto>
 
-    @get:ArraySchema(arraySchema = Schema(description = "Roles this business partner takes in relation to the sharing member. Sorted and duplicates removed by the service."))
+    @get:ArraySchema(arraySchema = Schema(description = "One or more of the roles, the business partner assumes with respect to the sharing member: Supplier, Customer. Sorted and duplicates removed by the service."))
     val roles: Collection<BusinessPartnerRole>
 
-    val legalEntity: IBaseLegalEntityComponent
+    @get:Schema(description = "The legal entity, on which the business partner provides a view.")
+    val legalEntity: IBaseLegalEntityRepresentation
 
-    val site: IBaseSiteComponent
+    @get:Schema(description = "The site, on which the business partner provides a view.")
+    val site: IBaseSiteRepresentation
 
-    val address: IBaseAddressComponent
+    @get:Schema(description = "The address, on which the business partner provides a view. ")
+    val address: IBaseAddressRepresentation
 }
 
-interface IBaseLegalEntityComponent {
+@Schema(description = "A legal entity representation adds context information to the legal entity, on which the business partner provides a view. Additionally, it contains some of the information from the assigned legal entity.")
+interface IBaseLegalEntityRepresentation {
 
-    @get:Schema(description = "BPNL of the golden record legal entity this business partner refers to")
-    val bpnL: String?
+    @get:Schema(description = "The BPNL of the legal entity, on which the business partner provides a view.")
+    val legalEntityBpn: String?
 
-    @get:Schema(description = "The name according to official registers.")
+    @get:Schema(description = "The name of the legal entity, on which the business partner provides a view, according to official registers.")
     val legalName: String?
 
-    @get:Schema(description = "Abbreviated name or shorthand.")
+    @get:Schema(description = "The abbreviated name of the legal entity, on which the business partner provides a view.")
     val shortName: String?
 
-    @get:Schema(description = "Technical key of the legal form.")
+    @get:Schema(description = "The legal form of the legal entity, on which the business partner provides a view.")
     val legalForm: String?
 
     @get:ArraySchema(arraySchema = Schema(description = "The list of classifications of the business partner, such as a specific industry. Sorted and duplicates removed by the service."))
     val classifications: Collection<IBusinessPartnerClassificationDto>
 }
 
-interface IBaseSiteComponent {
-    @get:Schema(description = "BPNS of the golden record site this business partner refers to")
-    val bpnS: String?
+@Schema(description = "A site representation adds context information to the site, on which the business partner provides a view. Additionally, it contains some of the information from the assigned site.")
+interface IBaseSiteRepresentation {
+    @get:Schema(description = "The BPNS of the site, on which the business partner provides a view.")
+    val siteBpn: String?
 }
 
-interface IBaseAddressComponent : IBaseBusinessPartnerPostalAddressDto {
-    @get:Schema(description = "BPNA of the golden record address this business partner refers to")
-    val bpnA: String?
+@Schema(description = "An address representation adds context information to the address, on which the business partner provides a view. Additionally, it contains most of the information from the assigned address.")
+interface IBaseAddressRepresentation : IBaseBusinessPartnerPostalAddressDto {
+    @get:Schema(description = "The BPNA of the address, on which the business partner provides a view.")
+    val addressBpn: String?
+
+    @get:Schema(description = "One of the address types: Legal Address, Site Main Address, Legal and Site Main Address, Additional Address. ")
+    override val addressType: AddressType?
+
+    @get:Schema(description = "The physical postal address of the address, on which the business partner provides a view, such as an office, warehouse, gate, etc.")
+    override val physicalPostalAddress: IBasePhysicalPostalAddressDto?
+
+    @get:Schema(description = "The alternative postal address of the address, on which the business partner provides a view, for example if the goods are to be picked up somewhere else.")
+    override val alternativePostalAddress: IBaseAlternativePostalAddressDto?
 }

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

@@ -19,12 +19,16 @@
 
 package org.eclipse.tractusx.bpdm.gate.api.model
 
+import io.swagger.v3.oas.annotations.media.Schema
 import org.eclipse.tractusx.bpdm.common.dto.IBusinessPartnerIdentifierDto
 
 data class BusinessPartnerIdentifierDto(
 
+    @get:Schema(description = "The type of the identifier.")
     override val type: String?,
+    @get:Schema(description = "The value of the identifier like “DE123465789.")
     override val value: String?,
+    @get:Schema(description = "The name of the official register, where the identifier is registered. For example, a Handelsregisternummer in Germany is only valid with its corresponding Registergericht and Registerart.")
     override val issuingBody: String?
 
 ) : IBusinessPartnerIdentifierDto

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

@@ -28,7 +28,7 @@ interface IBaseBusinessPartnerGateDto : IBaseBusinessPartnerDto {
     @get:Schema(description = CommonDescription.externalId)
     val externalId: String
 
-    @get:Schema(description = "True if the sharing member declares itself as the owner of the business partner.")
+    @get:Schema(description = "Indicates whether the sharing member claims (in the initial upload) the business partner to belong to the company data of the sharing member.")
     val isOwnCompanyData: Boolean
 }
 

bpdm-gate-api/src/main/kotlin/org/eclipse/tractusx/bpdm/gate/api/model/request/BusinessPartnerInputRequest.kt

@@ -24,9 +24,9 @@ import org.eclipse.tractusx.bpdm.common.dto.BusinessPartnerRole
 import org.eclipse.tractusx.bpdm.gate.api.model.BusinessPartnerIdentifierDto
 import org.eclipse.tractusx.bpdm.gate.api.model.BusinessPartnerStateDto
 import org.eclipse.tractusx.bpdm.gate.api.model.IBaseBusinessPartnerGateDto
-import org.eclipse.tractusx.bpdm.gate.api.model.response.AddressComponentInputDto
-import org.eclipse.tractusx.bpdm.gate.api.model.response.LegalEntityComponentInputDto
-import org.eclipse.tractusx.bpdm.gate.api.model.response.SiteComponentInputDto
+import org.eclipse.tractusx.bpdm.gate.api.model.response.AddressRepresentationInputDto
+import org.eclipse.tractusx.bpdm.gate.api.model.response.LegalEntityRepresentationInputDto
+import org.eclipse.tractusx.bpdm.gate.api.model.response.SiteRepresentationInputDto
 
 @Schema(
     description = "Generic business partner with external id",
@@ -40,8 +40,8 @@ data class BusinessPartnerInputRequest(
     override val states: Collection<BusinessPartnerStateDto> = emptyList(),
     override val roles: Collection<BusinessPartnerRole> = emptyList(),
     override val isOwnCompanyData: Boolean = false,
-    override val legalEntity: LegalEntityComponentInputDto = LegalEntityComponentInputDto(),
-    override val site: SiteComponentInputDto = SiteComponentInputDto(),
-    override val address: AddressComponentInputDto = AddressComponentInputDto()
+    override val legalEntity: LegalEntityRepresentationInputDto = LegalEntityRepresentationInputDto(),
+    override val site: SiteRepresentationInputDto = SiteRepresentationInputDto(),
+    override val address: AddressRepresentationInputDto = AddressRepresentationInputDto()
 
 ) : IBaseBusinessPartnerGateDto

bpdm-gate-api/src/main/kotlin/org/eclipse/tractusx/bpdm/gate/api/model/response/BusinessPartnerDto.kt

@@ -38,9 +38,9 @@ data class BusinessPartnerInputDto(
     override val states: Collection<BusinessPartnerStateDto> = emptyList(),
     override val roles: Collection<BusinessPartnerRole> = emptyList(),
     override val isOwnCompanyData: Boolean = false,
-    override val legalEntity: LegalEntityComponentInputDto = LegalEntityComponentInputDto(),
-    override val site: SiteComponentInputDto = SiteComponentInputDto(),
-    override val address: AddressComponentInputDto = AddressComponentInputDto(),
+    override val legalEntity: LegalEntityRepresentationInputDto = LegalEntityRepresentationInputDto(),
+    override val site: SiteRepresentationInputDto = SiteRepresentationInputDto(),
+    override val address: AddressRepresentationInputDto = AddressRepresentationInputDto(),
 
     @get:Schema(description = CommonDescription.createdAt)
     val createdAt: Instant,
@@ -50,21 +50,21 @@ data class BusinessPartnerInputDto(
 
 ) : IBaseBusinessPartnerGateDto
 
-data class LegalEntityComponentInputDto(
-    override val bpnL: String? = null,
+data class LegalEntityRepresentationInputDto(
+    override val legalEntityBpn: String? = null,
     override val legalName: String? = null,
     override val shortName: String? = null,
     override val legalForm: String? = null,
     override val classifications: Collection<BusinessPartnerClassificationDto> = emptyList()
-) : IBaseLegalEntityComponent
+) : IBaseLegalEntityRepresentation
 
-data class SiteComponentInputDto(
-    override val bpnS: String? = null
-) : IBaseSiteComponent
+data class SiteRepresentationInputDto(
+    override val siteBpn: String? = null
+) : IBaseSiteRepresentation
 
-data class AddressComponentInputDto(
-    override val bpnA: String? = null,
+data class AddressRepresentationInputDto(
+    override val addressBpn: String? = null,
     override val addressType: AddressType? = null,
     override val physicalPostalAddress: PhysicalPostalAddressDto = PhysicalPostalAddressDto(),
     override val alternativePostalAddress: AlternativePostalAddressDto = AlternativePostalAddressDto()
-) : IBaseAddressComponent
+) : IBaseAddressRepresentation

bpdm-gate-api/src/main/kotlin/org/eclipse/tractusx/bpdm/gate/api/model/response/BusinessPartnerOutputDto.kt

@@ -37,8 +37,8 @@ data class BusinessPartnerOutputDto(
     override val states: Collection<BusinessPartnerStateDto> = emptyList(),
     override val roles: Collection<BusinessPartnerRole> = emptyList(),
     override val isOwnCompanyData: Boolean = false,
-    override val legalEntity: LegalEntityComponentOutputDto,
-    override val site: SiteComponentOutputDto = SiteComponentOutputDto(),
+    override val legalEntity: LegalEntityRepresentationOutputDto,
+    override val site: SiteRepresentationOutputDto = SiteRepresentationOutputDto(),
     override val address: AddressComponentOutputDto,
 
     @get:Schema(description = CommonDescription.createdAt)
@@ -53,28 +53,28 @@ data class BusinessPartnerOutputDto(
     description = "Legal Entity properties of business partner output data",
     requiredProperties = ["bpnL"]
 )
-data class LegalEntityComponentOutputDto(
-    override val bpnL: String,
+data class LegalEntityRepresentationOutputDto(
+    override val legalEntityBpn: String,
     override val legalName: String? = null,
     override val shortName: String? = null,
     override val legalForm: String? = null,
     override val classifications: Collection<BusinessPartnerClassificationDto> = emptyList()
-) : IBaseLegalEntityComponent
+) : IBaseLegalEntityRepresentation
 
 @Schema(
     description = "Site properties of business partner output data"
 )
-data class SiteComponentOutputDto(
-    override val bpnS: String? = null
-) : IBaseSiteComponent
+data class SiteRepresentationOutputDto(
+    override val siteBpn: String? = null
+) : IBaseSiteRepresentation
 
 @Schema(
     description = "Address properties of business partner output data",
     requiredProperties = ["bpnA"]
 )
 data class AddressComponentOutputDto(
-    override val bpnA: String,
+    override val addressBpn: String,
     override val addressType: AddressType? = null,
     override val physicalPostalAddress: PhysicalPostalAddressDto = PhysicalPostalAddressDto(),
     override val alternativePostalAddress: AlternativePostalAddressDto = AlternativePostalAddressDto()
-) : IBaseAddressComponent
+) : IBaseAddressRepresentation