PaloAltoNetworks / docusaurus-openapi-docs

🦝 OpenAPI plugin for generating API reference docs in Docusaurus v3.
https://docusaurus-openapi.tryingpan.dev
MIT License
704 stars 236 forks source link

Example request body doesn't honor readOnly property #347

Closed colin-mckibben-sp closed 1 year ago

colin-mckibben-sp commented 1 year ago

Describe the bug

If a schema marks a property as readOnly: true, then the resulting markdown will remove the property from the request body schema, but it will not remove it from the example request body.

The following schema, truncated for brevity, marks id, created, and modified as readOnly.

type: object
properties:
  id:
    type: string
    description: The ID of the Access Profile
    example: 2c91808a7190d06e01719938fcd20792
    readOnly: true
  name:
    type: string
    description: Name of the Access Profile
    example: Employee-database-read-write
  description:
    type: string
    description: Information about the Access Profile
    example: Collection of entitlements to read/write the employee database
  created:
    type: string
    description: Date the Access Profile was created
    format: 'date-time'
    example: '2021-03-01T22:32:58.104Z'
    readOnly: true
  modified:
    type: string
    description: Date the Access Profile was last modified.
    format: 'date-time'
    example: '2021-03-02T20:22:28.104Z'
    readOnly: true
...

The schema renders correctly, omitting those three fields: image

However, the example request body includes those three fields, which is incorrect. image

Expected behavior

The example request body should honor the readOnly property and not render any property that is marked as readOnly: true.

Current behavior

The example request body ignores the readOnly property and displays an example for all properties in the schema.

Possible solution

Steps to reproduce

Live example can be found here: https://developer.sailpoint.com/idn/api/beta/create-access-profile

Context

This issue impacts our users who expect the example request body to be an accurate depiction of what can be included the request. Having readOnly properties in the example request will result in errors and confuse users.

Your Environment

Docusaurus: version 2.2.0

welcome-to-palo-alto-networks[bot] commented 1 year ago

:tada: Thanks for opening your first issue here! Welcome to the community!

sserrata commented 1 year ago

Fix is now available for preview using canary release 0.0.0-520