search

PaloAltoNetworks / docusaurus-openapi-docs

🦝 OpenAPI plugin for generating API reference docs in Docusaurus v3.
https://docusaurus-openapi.tryingpan.dev
MIT License
598 stars 206 forks source link

Schema details not shown with `oneOf` for primitive types #708

Open jean-baptiste-exorde opened 6 months ago

jean-baptiste-exorde commented 6 months ago

Describe the bug

Hi, I have an issue when using oneOf in the schema. If the schema referenced by oneOf is a primitive type (like integer or string), only the type is shown in the documentation, not the details of the schema. But, if the schema is an object, the details are shown.

Expected behavior

Schema details should be shown for primitive types (example with redocly):

expected

Current behavior

Only the type is shown for primitive types:

integer_ko

Full schema is shown for object type:

object_ok

Steps to reproduce

  1. Use the following openapi spec.
  2. run yarn docusaurus gen-api-docs all && yarn start
  3. Open docusaurus an go to the page that shows the API schema

In the example below, the Foo schema is an oneOf of 3 base schemas: two primitive types and one object.

I put the Foo schema in in the request body and the response, the result is the same: the object schema is shown as expected, but the integer and string schema are not.

Openapi spec

```yaml openapi: 3.0.3 servers: - url: https:// info: title: "" version: "1.0" paths: /demo: get: summary: Demo requestBody: content: application/json: schema: $ref: "#/components/schemas/Foo" responses: "200": description: successful operation content: application/json: schema: $ref: "#/components/schemas/Foo" components: securitySchemes: basicAuth: type: http scheme: basic schemas: integerSchema: type: integer format: int32 description: I'm an integer! multipleOf: 5 minimum: 5 maximum: 6000 default: 60 stringSchema: type: string description: I'm a string! pattern: ^some.*pattern$ default: some default value example: example value objectSchema: type: object properties: id: $ref: "#/components/schemas/integerSchema" name: $ref: "#/components/schemas/stringSchema" xml: name: Tag Foo: oneOf: - $ref: "#/components/schemas/integerSchema" - $ref: "#/components/schemas/stringSchema" - $ref: "#/components/schemas/objectSchema" ```

Context

Latest version of Docusaurus and OpenAPI plugin, fresh install.

sserrata commented 2 weeks ago

Hi @jean-baptiste-exorde, thanks for reporting. I'll add it to our roadmap.