As a follow up to this. I attempted to add my own API endpoint to return a file stream - however this does not appear to be supported within the 7.3.5 ga6 version of REST Builder: 

# rest-opeenapi.yaml

...
...
  "/app/image/{documentId}":
    parameters:
      - in: path
        name: documentId
        schema:
          format: int64
          type: integer
        required: true
        description: id of the document
    get:
      summary: Get ImageFileStream for documentId
      responses:
        '200':
          description: OK
          content:
            application/octet-stream:
              schema: '#/components/schemas/ImageFileStream'
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
      description: 'Based on a documentId, return a binary file stream for the asset'
      tags: [ImageFileStream]

...
...
components:
  schemas:
    ImageFileStream:
      type: string
      description: File stream for an image
      title: Image file stream
      format: binary
      readOnly: true


Resulting exception thrown by RESTBuilder: 

Exception in thread "main" java.lang.RuntimeException: Error generating REST API
Error in file "rest-openapi.yaml": null
	at com.liferay.portal.tools.rest.builder.RESTBuilder.main(RESTBuilder.java:126)

This is mentioned as supported within OpenAPI v3.0 - refer to the section Response That Returns a File in the OpenAPI spec.

While the spec indicates that one can just indicate a binary response - I have to incorporate a tag/resource in the RESTBuilder yaml - otherwise no Resource gets built. 

Again - any information on the above would be most helpful.

Mmm... it's a good question, most use cases getting images from the APIs are for retrieving meta information of *public* images. I guess that your use case is that you want to render private images and you want them to stay that way. So you can not embed them directly in an <img tag...

So we can...

-> Embed them. I would not recomment embedding images in a GET collection request because you can end with a large request (>1MB) that timeouts/get's dropped and chaos occurs. If you are getting images in a small number of requests (0-10) and those images are small (like >200kb) I don't see the problem, the browser would have to do an extra request either way of that similar size. You lose some things like caching the image automatically and some optimizations but I think it's Ok.

-> Use the contentUrl. That was the planned path. But it that image is private we have to pass the token in the request. There is a limitation with basic auth right now that will be removed in the future but OAuth2/tokens is fine.

-> Use adapted Images that are usually public and work with Basic Auth. The path http://localhost:8080/o/adaptive-media/image/12345/Preview-1000x0/AnImage-123.png?t=1538761582000 should work for those...

-> Create an API that returns the image.