How to hide private content in the specification

Overview

To enable hiding private API, parameter, property or tag in the public specification a dedicated decorator was designed: x-cdq-private.js. To activate the hide feature property x-cdq-private must be added manually in the component specification when it's necessary.

Info

The presented decorator is activated on the Developer Portal only.

To hide private API, parameter, property or tag in the public Developer Portal, the below custom property is needed:

x-cdq-private: true

The flag must be set inside the element you need to hide. When the element is linked to the private element only the private element will be hidden but not the link. It's expected behavior because decorator hides only the element with the x-cdq-private property. Check the Nested flag use case for more details.

Info

New property is replacing the x-hide or x-public used before.

Hide the private API, parameter, property or tag.

To hide private content:

Go to desired component specification.
Find the API, parameter, property or tag to hide.
Copy the below property and paste it into the component specification.

x-cdq-private: true

Paste it directly to:

paths:
  /addnewbusinesspartner:
    post:
      x-cdq-private: true
      summary: Add a new Business Partner to the Storage
      description: ''

 parameters:
        - name: status
          x-cdq-private: true
          in: query
          description: Status values that need to be considered for filter

properties:
    id:
      x-cdq-private: true
      type: integer
      format: int64
    category:
      $ref: '#/components/schemas/Category'

tags:
  - name: Business Partner
    descriptions: Business Partner related operations
    x-cdq-private: true

Delete the below property if it exists.

x-hide: "boolean value"

Nested flag Use case

Consider the following example of a nested flag. The EmailVerificationSummary object contains a property isBreachedDomain which is flagged as private.

Wrong usage of the private flag

Object:

EmailVerificationSummary:
  type: object
  description: Summary of the email verification result.yaml.
  properties:
    isBreachedDomain:
      $ref: '#/components/schemas/IsBreachedDomain'
    isBreachedEmail:
      $ref: '#/components/schemas/IsBreachedEmail'

Flagged property:

IsBreachedDomain:
  type: boolean
  x-cdq-private: true
  description: Indicates whether the domain has been found in data breaches.
  example: false

Error

This configuration will lead to the build error due to an unreasonable link.

Correct usage of the private flag