PaloAltoNetworks / PaloAltoNetworks/docusaurus-openapi-docs
additionalProperties object specified via $ref is rendered with the ref's name in the description
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
$ cat Downloads.yaml
type: object
properties:
dnclient:
type: object
properties:
latest:
description: Download links for the latest DNClient version
$ref: './DownloadsDNClientLinks.yaml'
additionalProperties:
$ref: './DownloadsDNClientLinks.yaml'
$ cat DownloadsDNClientLinks.yaml
type: object
description: Download links for a given DNClient version
properties:
linux-amd64:
type: string
linux-arm64:
type: string
macos-universal:
type: string
macos-universal-dmg:
type: string
windows-amd64:
type: string
windows-arm64:
type: string
additionalProperties:
x-additionalPropertiesName: os-platform
type: string
Expected behavior
Current behavior
Possible solution
Adding the file name of the $ref is confusing as a docs consumer, as it has no relevance to me. It's simply an implementation detail of how the OpenAPI spec is defined. The hardcoded property doesn't show the $ref, but additionalProperties does. My preference is to remove the $ref name from the output.
Steps to reproduce
Build docs using specs listed above.
Screenshots
See above.
Context
n/a
Your Environment
- Version used: docusaurus 2.4.0 & docusaurus-plugin-openapi-docs 2.0.0-beta.2
- Environment name and version (e.g. Chrome 59, node.js 5.4, python 3.7.3): node.js 18.7.0
- Operating System and version (desktop or mobile): Linux
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
Reproduce the rendering with Downloads.yaml and DownloadsDNClientLinks.yaml, using the documented build process and the versions in the report. Compare the additionalProperties output with the hardcoded property that uses the same $ref. Done means the generated documentation no longer exposes the referenced file name for additionalProperties while retaining the intended description.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi, typescript
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100