HiDeoo / starlight-openapi

Starlight plugin to generate documentation from OpenAPI/Swagger specifications
https://starlight-openapi.vercel.app
MIT License
112 stars 14 forks source link

Certain fields are not parsed correctly #12

Closed huijing closed 1 year ago

huijing commented 1 year ago

Describe the bug

There are 2 striking issues that occur when I'm trying to parse our OpenAPI specification.

  1. When oneOf is used, the plugin parses the array into tabs, but the tab item headers are unknown. Please refer to attached screenshot which shows the specification and rendered output using Swagger Editor, compared with the plugin output

    Screenshot 2023-10-18 at 11 56 41 PM

  2. When the type is an array, nested information is not rendered. Please refer to attached screenshots as well.

    Screenshot 2023-10-19 at 11 51 50 AM

    Screenshot 2023-10-19 at 12 01 02 PM

To Reproduce

  1. Load the YAML files attached at the end of the issue
  2. Go to the page for Grant Request, which will show up nested under grant in the generated sidebar item
    1. At the request body section, for the access_token field, as well as the interact field, you can see the array issue
    2. Scroll further down to Responses and you can see the unknown tab title issue
  3. Another page where this happens is the Create a quote page nested under quote in the generated sidebar item
    1. Under request body, you can see the unknown tab item issue as well
    2. On this page you can also see that authorizations ends up being rendered as a list item and nothing more, this might be more of a additional feature than a bug maybe?

Expected behavior

  1. I'm not sure if the tabs are necessary, but based on the behaviour on SwaggerEditor, I suppose just putting the array index as the tab title would be better than "unknown"?
  2. For this, the expected behaviour would be that the nested information is parsed throughly, just like it is being done for items of type object.

How often does this bug happen?

Every time

System Info

But this issue is unrelated to the system.

Additional Context

These are the specification files where the issues occur. You can upload them to https://editor-next.swagger.io/ for see the comparison versus loading them with the plugin.

HiDeoo commented 1 year ago

Thanks for the detailed report. These issues should be fixed in v0.3.1 that I just published on npm.

Some arrays were missing object details, they should now render correctly.

SCR-20231019-kwyk

Still related to arrays, enums informations were not displayed correctly, this should now be fixed.

SCR-20231019-lexs

Regarding the "unknown" oneOf, 2 issues were involved: the labels of the tabs being "unknown" and the tabs content actually missing. Both should render correctly now.

SCR-20231019-kivy SCR-20231019-kiyg

Regarding the authorizations, each authorization is now a link to the corresponding security scheme which contains all the informations.

SCR-20231019-lzxg SCR-20231019-lzug