PaloAltoNetworks / PaloAltoNetworks/docusaurus-openapi-docs

additionalProperties object specified via $ref is rendered with the ref's name in the description

Open
#539 1 comment 0 reactions 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

$ 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

Screenshot 2023-04-07 at 2 39 36 PM

Current behavior

Screenshot 2023-04-07 at 2 18 30 PM

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

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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.