cloud-annotations / docusaurus-openapi

🦕 OpenAPI plugin for generating API reference docs in Docusaurus v2.
https://docusaurus-openapi.netlify.app
MIT License
498 stars 82 forks source link

Add visual indicator for deprecated request/response body field #246

Open Krismix1 opened 1 year ago

Krismix1 commented 1 year ago

If a request/response field is marked as deprecated there is no visual indicator in the UI. I think having some indicator to be useful, as that would prevent new consumers of an API from using a field that is meant to be deleted. I can see that the deprecated field is not included in the example request, which is already a good thing. But having something in the schema section could make it more obvious, especially for cases where the schema can have a lot of fields or to distinguish that

image

Version: 0.6.4 Commit: 0beb11b248e34e2b88f171406fc4fb04a390f065 Reproduction spec:

openapi: 3.0.0
servers: []
info:
  description: |
    Example
  version: 1.0.0
  title: Swagger Petstore YAML
tags:
  - name: pet
    description: Everything about your Pets
paths:
  /pet:
    post:
      tags:
        - pet
      summary: Add a new pet to the store
      description: Add new pet to the store inventory.
      operationId: addPet
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pet"
        "405":
          description: Invalid input
      requestBody:
        $ref: "#/components/requestBodies/Pet"
components:
  schemas:
    Pet:
      type: object
      properties:
        name:
          description: The name given to a pet
          type: string
          example: Guru
          deprecated: true
        age:
          description: The age of the pet
          type: number
          example: 5
  requestBodies:
    Pet:
      content:
        application/json:
          schema:
            allOf:
              - description: My Pet
                title: Pettie
              - $ref: "#/components/schemas/Pet"
      description: Pet object that needs to be added to the store
      required: true