Non-required yaml spec fields showing as required in generated documentation

[outofthisworld]

Describe the bug

My yaml spec doc contains the following non-required headers for a POST endpoint:

      parameters:
        - schema:
            type: string
          in: header
          name: Authorization
          required: false
        - schema:
            type: string
          in: header
          name: X-Api-Key
          required: false
        - schema: {}
          in: header
          name: X-Request-Id
          required: false

After generating my API's yaml spec in a cloned version of the github example project recommended in the docs, the UI shows these headers as 'required'. I have attached an image below.

On a side note and unrelated to this issue, I was wondering if someone could elaborate on how endpoints are grouped in the sidebar of the docs.

I have each endpoint in my api tagged with a tag specific to the resource. E.G /pets endpoints get the tag "pets" (incl del, put,patch) - and the same for other resources. The sidebar nav seems to group everything randomly, rather than the endpoints by their associated tag. Swagger displays them exactly how I would have expected and groups them by this tag. Is there a way I can accomplish a similar thing using this plugin?

Expected behavior

Non-required headers should not be labeled as required.

Current behavior

The opposite of above.

Possible solution

Fix UI.

Steps to reproduce

1. Clone recommended git project
2. Generate docs from a spec with non-required headers
3. Serve project
4. View output

Screenshots

Context

Just inaccurate.

Your Environment

Node 19, using cloned example repo from main github project page.

[fbolton]

@outofthisworld Having exactly the same problem. It's a pretty severe bug from our perspective, as we don't want our customers to think that the optional parameters are required.

[sserrata]

@outofthisworld can you provide a sample spec or steps to reproduce?

[fbolton]

@sserrata I can provide a sample spec - https://platform.iceye.com/docs/api/tasking/v1/specification/tasking_api_v1_openapi.yaml

Using these versions:

• Docusaurus 2.4.3
• docusaurus-plugin-openapi-docs ^2.1.3
• docusaurus-theme-openapi-docs 2.1.0

The POST /tasks (createTask) operation provides a good example of this bug in practice. According to the spec, only the contractID, pointOfInterest, acquisitionWindow and imagingMode are required properties in the request body. But when the OpenAPI doc is generated by the plugin, it shows almost all of the 13 properties as REQUIRED, except for incidenceAngle and deliveryLocations.

[sserrata]

Unable to reproduce using provided schema. Likely fixed in #848. Try the latest canary release to test or wait for the next official 2.x release.

[fbolton]

@sserrata Thanks very much for testing the schema. I'll try the latest canary release to see if that fixes the problem on my side.

[fbolton]

Confirmed that the problem is now fixed, using the latest packages on the main branch of docusaurus-plugin-openapi-docs. Thanks very much for your help, @sserrata !

[fbolton]

@sserrata After a bit of experimentation with different plugin versions, I accidentally stumbled across the root cause of this isssue. The problem with parameters being marked as Required when they are not, happens when the docusaurus-plugin-openapi-docs package and docusaurus-theme-openapi-docs package versions are out of alignment.

Previously, I had the following dependencies in my package.json file:

"docusaurus-plugin-openapi-docs": "^2.1.3",
"docusaurus-theme-openapi-docs": "2.1.0",

If I change the package dependencies so that they are in agreement:

"docusaurus-plugin-openapi-docs": "^2.1.3",
"docusaurus-theme-openapi-docs": "^2.1.3",

The problem with the mis-labeled Required parameters is gone.

I checked the template (docusaurus-template-openapi-docs) that I used to generate my settings and found that template has the versions correctly aligned. So this version misalignment was entirely my own fault!

@outofthisworld - FYI