An imaginary Potion Inventory API with multiple resource representations described

openapi.yaml

openapi: 3.1.0
info:
  title: Potion Inventory API
  contact:
    url: https://github.com/lornajane
  version: 1.0.0
paths:
  /potions:
    get:
      summary: Get a list of potions
      description: Retrieves a collection of potions with different levels of detail based on the requested format.
      parameters:
        - name: format
          in: query
          description: Specifies the representation format of the potion collection.
          required: false
          schema:
            type: string
            enum: [light, detailed, very-detailed]
            default: light
      responses:
        '200':
          description: A list of potions
          content:
            application/vnd.potions.light+json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      description: The name of the potion.
                    effect:
                      type: string
                      description: Primary effect of the potion.
              examples:
                potion1:
                  value:
                    - name: Gigglebrew
                      effect: Causes uncontrollable laughter
                    - name: Luckyleaf Elixir
                      effect: Temporarily enhances good fortune
                potion2:
                  value:
                    - name: Snoozejuice
                      effect: Instantly puts the drinker to sleep
            application/vnd.potions.detailed+json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      description: The name of the potion.
                    effect:
                      type: string
                      description: Primary effect of the potion.
                    ingredients:
                      type: array
                      items:
                        type: string
                      description: List of ingredients used.
                    duration:
                      type: string
                      description: Duration of the effect.
              examples:
                potion1:
                  value:
                    - name: Gigglebrew
                      effect: Causes uncontrollable laughter
                      ingredients: [Giggleroot, Honeydew, Smiling Fern]
                      duration: 1 hour
                    - name: Luckyleaf Elixir
                      effect: Temporarily enhances good fortune
                      ingredients: [Warm Milk, Velvet Petals, Cozyroot]
                      duration: 2 hours
                potion2:
                  value:
                    - name: Snoozejuice
                      effect: Instantly puts the drinker to sleep
                      ingredients: [Slumberberries, Nightshade, Woolleaf]
                      duration: 8 hours
            application/vnd.potions.very-detailed+json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      description: The name of the potion.
                    effect:
                      type: string
                      description: Primary effect of the potion.
                    ingredients:
                      type: array
                      items:
                        type: string
                      description: List of ingredients used.
                    duration:
                      type: string
                      description: Duration of the effect.
                    brewing_instructions:
                      type: string
                      description: Detailed brewing instructions.
                    side_effects:
                      type: array
                      items:
                        type: string
                      description: Possible side effects.
                    origin:
                      type: string
                      description: Historical origin of the potion.
              examples:
                potion1:
                  value:
                    - name: Gigglebrew
                      effect: Causes uncontrollable laughter
                      ingredients: [Giggleroot, Honeydew, Smiling Fern]
                      duration: 1 hour
                      brewing_instructions: Brew giggleroot and honeydew over low flame, adding smiling fern just before boiling. Allow to cool before consumption.
                      side_effects: [Snorting, Occasional Snort-Laughter]
                      origin: Discovered accidentally by the infamous jester Wigglybottom.
                potion2:
                  value:
                    - name: Luckyleaf Elixir
                      effect: Temporarily enhances good fortune
                      ingredients: [Four-Leaf Clover, Whispering Willow Sap, Stardust]
                      duration: 3 hours
                      brewing_instructions: Steep the clover in whispering willow sap under starlight, sprinkle stardust at dawn, and recite a wish.
                      side_effects: [Mild Overconfidence, Unexpected Coincidences]
                      origin: First crafted by the renowned herbalist Fortuna Greenfingers to escape a series of unfortunate events.
                potion3:
                  value:
                    - name: Snoozejuice
                      effect: Instantly puts the drinker to sleep
                      ingredients: [Slumberberries, Nightshade, Woolleaf]
                      duration: 8 hours
                      brewing_instructions: Crush slumberberries, mix with woolleaf infusion, and add a drop of nightshade. Let it rest under moonlight.
                      side_effects: [Grogginess, Sleepwalking]
                      origin: Traditionally brewed by moonlit monks to ensure restful slumber.
          content:
            application/vnd.potions.light+json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      description: The name of the potion.
                    effect:
                      type: string
                      description: Primary effect of the potion.
            application/vnd.potions.detailed+json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      description: The name of the potion.
                    effect:
                      type: string
                      description: Primary effect of the potion.
                    ingredients:
                      type: array
                      items:
                        type: string
                      description: List of ingredients used.
                    duration:
                      type: string
                      description: Duration of the effect.
            application/vnd.potions.very-detailed+json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      description: The name of the potion.
                    effect:
                      type: string
                      description: Primary effect of the potion.
                    ingredients:
                      type: array
                      items:
                        type: string
                      description: List of ingredients used.
                    duration:
                      type: string
                      description: Duration of the effect.
                    brewing_instructions:
                      type: string
                      description: Detailed brewing instructions.
                    side_effects:
                      type: array
                      items:
                        type: string
                      description: Possible side effects.
                    origin:
                      type: string
                      description: Historical origin of the potion.