PaloAltoNetworks / PaloAltoNetworks/docusaurus-openapi-docs

Content type with parameters does not work for prefilling the request example in ApiDemoPanel

Open
#603 2 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

bug roadmap
Dominant language
TypeScript
Stars
1.1k
Forks
315
Avg merge
7d 5h
Merged PRs (30d)
7

Description

Describe the bug

We are using parameters for content types and it seems that the Body component in the theme does not have a valid condition for it.
https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/main/packages/docusaurus-theme-openapi-docs/src/theme/ApiDemoPanel/Body/index.tsx

Example of Swagger path with content type that includes parameters such as charset:

  /store/order:
    post:
      tags:
        - store
      summary: Place an order for a pet
      description: ""
      operationId: placeOrder
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
            application/xml:
              schema:
                $ref: "#/components/schemas/Order"
        "400":
          description: Invalid Order
          content:
            application/json:
              example:
                status: 400
                message: "Invalid Order"
      requestBody:
        content:
          application/json; charset=utf-8:
            schema:
              $ref: "#/components/schemas/Order"

See requestBody > content > application/json; charset=utf-8:

Expected behavior

The request body example is pre-filled from the OpenAPI documentation even when specified parameters for Content Body. (application/json; charset=utf-8:)

Screenshot 2023-07-18 at 11 43 32

Current behavior

There is nothing pre-filled (application/json; charset=utf-8:).

Screenshot 2023-07-18 at 11 43 04

Possible solution

I'm not sure, but I can guess that all conditions in the Body component should probably not have an equal sign, but a condition on whether it contains a string.

From:

if (contentType === "application/json" || contentType.endsWith("+json"))

To something like:

if (contentType.includes("application/json") || contentType.endsWith("+json"))

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/includes

Steps to reproduce

  1. Clone https://github.com/PaloAltoNetworks/docusaurus-openapi-docs
  2. Change this line in petstore.yaml to application/json; charset=utf-8:
  3. Regenerate API doc (yarn clean-api && yarn gen-api)
  4. Start the demo (yarn watch:demo)
  5. Open http://localhost:3000/petstore_versioned/place-order and see that the demo request example is empty

Context

It seems that parameters are also valid according to MDN and OpenAPI specifications.

Your Environment

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in packages/docusaurus-theme-openapi-docs/src/theme/ApiDemoPanel/Body/index.tsx and reproduce the issue by changing the content type in demo/examples/petstore.yaml, then running yarn clean-api && yarn gen-api and yarn watch:demo. Done means the request body example is pre-filled for application/json; charset=utf-8, as it is for application/json.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi, react, typescript
Domain
documentation, frontend
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.