docs(specs): review Insights API spec

[kai687]

🧭 What and Why

Review and refine the OpenAPI specification for the Insights API.

🎟 JIRA Ticket: DOC-1110

Changes included:

• Correct parameter limits (maxItems for array types, maxLength for strings)
• Updated API, operation, and parameter descriptions and summaries
• Correct responses
• Example requests and responses, particularly errors
• Separate request bodies for allowed combinations of event attributes

🧪 Test

[netlify]

✅ Deploy Preview for api-clients-automation ready!

Name	Link
🔨 Latest commit	68482bd
🔍 Latest deploy log	https://app.netlify.com/sites/api-clients-automation/deploys/649457efe0fec80008de9ca4
😎 Deploy Preview	https://deploy-preview-1647--api-clients-automation.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[algolia-bot]

✗ The generated branch has been deleted.

If the PR has been merged, you can check the generated code on the main branch.
You can still access the code generated on main via this commit.

[kai687]

@shortcuts I exchanged anyOf with oneOf and most checks work, except some tests. oneOf is the correct semantics here, since any event can only match one schema exactly.

What do you think about this?

[gazconroy]

Some questions and tiny suggestions

[shortcuts]

@shortcuts I exchanged anyOf with oneOf and most checks work, except some tests. oneOf is the correct semantics here, since any event can only match one schema exactly.

What do you think about this?

This looks correct indeed, I wonder why this test doesn't work for Java. Could you double check properties properly match their type etc.?

[kai687]

@shortcuts This is why the test fails:

 ClickedObjectIDsAfterSearch events_12 = new ClickedObjectIDsAfterSearch();
        {
          ClickEvent eventType3 = ClickEvent.fromValue("view");
          events_12.setEventType(eventType3);
          String eventName3 = "Product Detail Page Viewed";
          events_12.setEventName(eventName3);
          String index3 = "products";
          events_12.setIndex(index3);
          String userToken3 = "user-123456";
          events_12.setUserToken(userToken3);
          long timestamp3 = 1641290601962L;
          events_12.setTimestamp(timestamp3);
          List<String> objectIDs3 = new ArrayList<>();
          {
            String objectIDs_04 = "9780545139700";
            objectIDs3.add(objectIDs_04);
            String objectIDs_14 = "9780439784542";
            objectIDs3.add(objectIDs_14);
          }
          events_12.setObjectIDs(objectIDs3);
        }

It's a view event, but it uses the request body for ClickedObjectIDsAfterSearch. It should use ViewedObjectIDs instead (likewise for the conversion test).

[shortcuts]

@shortcuts This is why the test fails:

 ClickedObjectIDsAfterSearch events_12 = new ClickedObjectIDsAfterSearch();
        {
          ClickEvent eventType3 = ClickEvent.fromValue("view");
          events_12.setEventType(eventType3);
          String eventName3 = "Product Detail Page Viewed";
          events_12.setEventName(eventName3);
          String index3 = "products";
          events_12.setIndex(index3);
          String userToken3 = "user-123456";
          events_12.setUserToken(userToken3);
          long timestamp3 = 1641290601962L;
          events_12.setTimestamp(timestamp3);
          List<String> objectIDs3 = new ArrayList<>();
          {
            String objectIDs_04 = "9780545139700";
            objectIDs3.add(objectIDs_04);
            String objectIDs_14 = "9780439784542";
            objectIDs3.add(objectIDs_14);
          }
          events_12.setObjectIDs(objectIDs3);
        }

It's a view event, but it uses the request body for ClickedObjectIDsAfterSearch. It should use ViewedObjectIDs instead (likewise for the conversion test).

Ah yessss there's an issue with the oneOf in the CTS that will pick the first oneOf type available if it can't correlate it correctly, cc @millotp

[shortcuts]

Ok so I can confirm this is definitely a test generation issue, I'll push a fix to your branch sorry for the blocker

[shortcuts]

#1654 fixes the CTS generation for this PR

[shortcuts]

so sadly #1654 fixes this PR issue but would create a new problem :( so I just removed the test for now and will investigate

[shortcuts]

Huge! It's kind of a breaking change but it's the best time to provide them :D

thanks for a lot for the review