PaloAltoNetworks / PaloAltoNetworks/docusaurus-openapi-docs
Content type with parameters does not work for prefilling the request example in ApiDemoPanel
Nobody has claimed this yet.
- 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:)
Current behavior
There is nothing pre-filled (application/json; charset=utf-8:).
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
- Clone https://github.com/PaloAltoNetworks/docusaurus-openapi-docs
- Change this line in petstore.yaml to
application/json; charset=utf-8: - Regenerate API doc (
yarn clean-api && yarn gen-api) - Start the demo (
yarn watch:demo) - 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.
- https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type
- https://swagger.io/specification/#media-types
Your Environment
- Version used: Current main commit https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/commit/28ec9357b7b50ea4cb060b2e7f9ab3d5118adad6 and v2.0.0-beta.3
- Environment name and version (e.g. Chrome 59, node.js 5.4, python 3.7.3): Brave Version 1.52.129 Chromium: 114.0.5735.198 (Official Build) (arm64); node v18.16.1, yarn 1.22.19
- Operating System and version (desktop or mobile): desktop MacOS Sonoma 14.0 Beta
- Link to your project: none
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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