docusaurus-openapi-docs: Broken formatting & multiple footers on 1.5.2+

Hi @TheCatLady, glad to hear it’s working so far. I think I isolated why some discriminators were causing issues - basically, they were resolving to “circular” refs. I was able to add some special handlers for those but they are very specifically tuned for the cases in your spec. I think this might also help explain why Redoc and Stoplight ignore them altogether. Here’s what I have so far:

https://user-images.githubusercontent.com/9343811/235236282-54c61e1d-dddd-41b1-ace9-d4cba3f590b2.mov

@sserrata Just saw that #561 was merged, woohoo! Really appreciate you taking the time and effort to resolve this issue for us. Eagerly awaiting the next release now 🤩

Hi @sserrata! Thanks so much for opening a PR with a fix for this issue so quickly!

I commented out the discriminator and tested your changes, and they look good so far! 😍

Also, I don’t have any control over authoring the API specs, so it would be nice if there was a way to handle the discriminator gracefully without needing to modify the spec.

Any solution that doesn’t require modifying the spec would be great, since it’s not like it was handled properly up until now anyway. 😄

@TheCatLady I opened #561 with the proposed fixes. Appreciate if you can help test with your specs. Just be sure to comment out the discriminator for now as noted above.

Thanks, I think I isolated the root cause. Basically, in createAnyOneOf, as we iterate through the schema and handle properties, items, allOf, etc., we should be “popping” those parts of the schema as they’re processed in order to avoid looping through them again. That explains why we see some duplicate properties.

Ahh, I see. I think it’s definitely preferable to have the correct labels, so I suppose Elements does a better job here.

Adding Redocly and Stoplight Elements repros for comparison:

Redocly: https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/someengineering/resoto.com/dh/deps/openapi/resotocore-edge.yml#tag/model/paths/~1model/get

Elements: https://elements-demo.stoplight.io/?spec=https://raw.githubusercontent.com/someengineering/resoto.com/dh/deps/openapi/resotocore-edge.yml#/paths/model/patch

It’s interesting to see how they each handle the Models endpoints. Redocly seems to get tripped up on the oneOf titles while ignoring the runtime_kind discriminator. Elements gets the oneOf schema titles/labels correctly but also seems to ignore the runtime_kind discriminator.

Should the runtime_kind discriminator be ignored in this case. What would be your expected behavior @TheCatLady? Between ReDoc and Elements, which do you think more closely handles your use case?

Wondering if changes in https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/397 could be the root cause, but it’s a bit odd that I only see the duplicate elements after a production build - I don’t observe it in dev server.