How to write a response for an MP3 file in OpenAPI YAML?

Question

I am writing an API YAML that returns an MP3 file. I am not familiar with multimedia responses. While going through Google I found that I can use the audio/mp3 content type. But I couldn't find any example showing how to do it. How should I address this audio content type?

Answer 1

OpenAPI 3.1

A binary file response is defined with just the media type and no schema:

openapi: 3.1.0
...

paths:
  /something:
    get:
      responses:
        '200':
          description: An audio file
          content:
            audio/mp3: {}

OpenAPI 3.0

Files are defined as binary strings (type: string + format: binary):

openapi: 3.0.3
...

paths:
  /something:
    get:
      responses:
        '200':
          description: An audio file
          content:
            audio/mp3:
              schema:
                type: string
                format: binary

OpenAPI 2.0

Binary file responses are defined with a type: file schema. Make sure to also specify the media type in the operation's produces list:

swagger: '2.0'
...

paths:
  /something:
    get:
      produces:
        - audio/mp3
      responses:
        200:
          description: An audio file
          schema:
            type: file