What does this OpenAPI/Swagger spec mean?

user_948730 0
Viewed 91

Spec in question:

openapi: '3.0.2'
info:
  title: Video Storage Server API
  version: '1.0'
servers:
  - url: http://localhost:8080
paths:
  /files/{fileid}:
    get:
      description: Download a video file by fileid. 
      parameters:
        - in: path
          name: fileid
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          headers:
            Content-Disposition:
              schema:
                type: string
          content:
            video/mp4:  # foo.mp4
              schema: 
                type: string
                format: binary
            video/mpeg: # bar.mpg 
              schema:
                type: string
                format: binary

I understand I need to have my server respond to a get request with fileid. The server stores video.

The response from server, should it be like a video that user can play in browser/Postman or should be the byte array of the video?

i.e. Should the response be:

Possible result 1

or

Possible result 2

Also, what does content#video/mp4 / content#video/mpeg mean? Do I need to set content-type in my response to be one of these 2?

What should my Content-Disposition be?

swagger-2.0 swagger openapi
2 Answers

The answer is the video as in the first example, or more correctly a stream of bytes that corresponds to the requested content type, video/mp4 or video/mpeg, with a Content-Disposition header.

If the response were to be a JSON block like in the 2nd example, the response content type would be application/json (or equivalent) and it would explicitly list the response object schema, ie there would be a filename, fileType and so on in the response.

user_14209410

The OpenAPI specification says:

  1. Publish an endpoint /files/{fileid}, where {fileid} is a path parameter.
  2. In the response, you provide:
  • Binary data of the video in the message body
  • Content-Type header with one of:
    • video/mp4
    • video/mpeg
  • Content-Disposition header with one of values:
    • Content-Disposition: inline (if the video shall be played inside the browser)
    • Content-Disposition: attachment; filename="filename.mp4" (if the video shall be downloaded)

See documentation for more about Content-Disposition header.

user_67035300
Related