Changelog generator doesn't recognize nested properties

[jmewes]

Observed result

• If top-level properties are added to a payload, the are included in the generated changelog.
• If nested properties are added to a payload, they are NOT included in the generated changelog.

Expected result

The Tech Writers also need the nested properties in the changelog.

Steps to reproduce

1. Add a top level property to a response payload and a nested property

e.g.

diff --git a/openapi.yaml b/openapi.yaml
index a5fa0a1..d9c4374 100644
--- a/openapi.yaml
+++ b/openapi.yaml
@@ -19959,12 +19959,18 @@ definitions:
       orderNote:
         type: string
         description: The merchant comment or note on the order.
+      orderNote2:
+        type: string
+        description: The merchant comment or note on the order 2.
       taxTotal:
         type: object
         properties:
           amount:
             type: number
             description: The amount of the tax total.
+          amount2:
+            type: number
+            description: The amount of the tax total 2.
           currency:
             type: string
             description: The currency of the tax total.

2. Create a commit with this change
3. Execute the script which generates the diff

{
git show HEAD~1:openapi.yaml > ${SPEC_FILE_1}
git show HEAD:openapi.yaml > ${SPEC_FILE_2}

./diff.sh ${SPEC_FILE_1} ${SPEC_FILE_2}
}

Console output

``` linbook-jm:beyond-api-changelog (master) janux$ { > git show HEAD~1:openapi.yaml > ${SPEC_FILE_1} > git show HEAD:openapi.yaml > ${SPEC_FILE_2} > > ./diff.sh ${SPEC_FILE_1} ${SPEC_FILE_2} > } ### What's New ### What's Deprecated ### What's Changed * `GET` /orders/search/find-by-cart-id Show order by cart ID Return Type Add orderNote2 //The merchant comment or note on the order 2. * `POST` /orders/{id}/send-order-document Send order document Return Type Add orderNote2 //The merchant comment or note on the order 2. * `PUT` /orders/{orderId}/billing-address Update billing address Return Type Add orderNote2 //The merchant comment or note on the order 2. * `POST` /orders/{orderId}/cancel Cancel order Return Type Add orderNote2 //The merchant comment or note on the order 2. * `POST` /orders/{orderId}/create-invoice Create invoice Return Type Add orderNote2 //The merchant comment or note on the order 2. * `POST` /orders/{orderId}/mark-as-viewed Mark order as viewed Return Type Add orderNote2 //The merchant comment or note on the order 2. * `PUT` /orders/{orderId}/order-note Update order note Return Type Add orderNote2 //The merchant comment or note on the order 2. * `PUT` /orders/{orderId}/shipping-address Update shipping address Return Type Add orderNote2 //The merchant comment or note on the order 2. ```

[jmewes]

To fix this issue swagger-diff.jar from https://github.com/Sayi/swagger-diff needs to be patched or replaced.

[ozscheyge]

https://github.com/Sayi/swagger-diff seems to be an abandoned project and not moving forward to OA3: https://github.com/Sayi/swagger-diff/issues/31 https://github.com/Sayi/swagger-diff/issues/5

[jmewes]

This diff generator might be worth to investigate: https://github.com/OpenAPITools/openapi-diff

[jmewes]

Maybe this tool could be tried as alternative for the diff generation:

https://github.com/Tufin/oasdiff