Fix response payload type for PutSubmodelById (3.2 Port)

[aaronzi]

This pull request fixes the response payload type for the PutSubmodelById operation in the Asset Administration Shell Repository OpenAPI specification. Specifically, when a submodel is created (status code 201), the response now correctly returns a Submodel object instead of a Reference. The changelog has also been updated to reflect this fix.

API Specification Fixes:

• The description for the 201 response in AssetAdministrationShellRepositoryServiceSpecification/V3.2_SSP-001.yaml was updated to clarify that a submodel is created, not a reference.
• The response schema for status code 201 now returns a Submodel instead of a Reference for the PutSubmodelById operation.

Documentation Updates:

• The changelog (changelog.adoc) now documents this fix under minor changes, referencing the related issue.

Related Issues

See #601

Cherry picked ec5b1d1 from #615

[CLAassistant]

All committers have signed the CLA.

[mjacoby]

The default behavior of PUT request in the AAS is updating existing elements and returning 204 No Content without any payload.

The only times this pattern is broken for PUT /shells/{aasIdentifier} and PUT /submodels/{submodelIdentifier}. In these cases the description says "Creates or updates existing ..." and the method returns either 201 is a new element has been created or 204 if an existing element has been updated.

Your proposal does not match any of the two existing patterns.

[aaronzi]

I agree with all you sentences @mjacoby except the last one. I did not change anything when it comes to when which status is returned. I just fixed the return type in the case of a 201 status.

[sebbader-sap]

The default behavior of PUT request in the AAS is updating existing elements and returning 204 No Content without any payload.

The only times this pattern is broken for PUT /shells/{aasIdentifier} and PUT /submodels/{submodelIdentifier}. In these cases the description says "Creates or updates existing ..." and the method returns either 201 is a new element has been created or 204 if an existing element has been updated.

Your proposal does not match any of the two existing patterns.

@mjacoby this is more like a general remark on the PUT endpoint design, not affecting this bugfix, right?

[mjacoby]

I understand that fixing the return type (from Reference to Submodel) and the whole upsert a two separate things. However, your commit not only contains the fix of the return type but also introduces upsert behavior in the file Entire-API-Collection/V3.2.yaml. This is the only reason I brought up the upsert topic here - because I did not expect a fix to introduce new functionality.

I am fine with the part of the PR fixing the return type, but the whole upsert thing is more complex than this. I also noticed that the PR description mentions that you changed the response code to 201 in V3.2_SSP-001.yaml and V3.2_SSP-005.yaml which is not what PR actually contains (only a change to Entire-API-Collection/V3.2.yaml).

I am therefore confused about the PR, its intention and scope and if the code matches the description of the PR's content.

[aaronzi]

Ah, now I get your remark. The description was copilot generated. I guess I have missed this in my review of that text.

Regarding the change in the API-Collection/V3.2.yaml, I thought that document should always be aligned to the individual services openapi files. I found this inconsistency there that the 201 response was missing entirely. I added it there as well. If that file should not be maintained alongside the individual services, I can of course remove that change again @mjacoby.