$batch documentation about odata-openapi

[ralfhandl]

Batch Requests are very important and have been significantly enhanced with OData V4.

We even introduced JSON Batch Format because the multipart format isn't for the faint of heart.

However: Swagger UI has no support for multipart request bodies, so showing the /$batch path in Swagger/OpenAPI wouldn't help much for those unfamiliar with OData. And those familiar with OData will know that it is there, and how to use it.

What documentation would you expect on the /$batch path in addition to a link to the OData specification?

[Tiberriver256]

Maybe just a POST /batch$ endpoint, a short description and a link to the OData specification or OData documentation?

Just so developers are aware.

[fbunsmann]

I would agree that a short description and a link to the ODATA Specification would definitely help. Below is just a first idea how it could look like in swagger 2.0. Of course it would be great it if the example for this endpoint would use one or more endpoints which actually exist in the specification.

paths:
  /$batch:
    post:
      summary: Using the $batch endpoint, multiple requests can be bundled into a single one.
      description: Group multiple operations into a single HTTP request payload, see [Batch Requests](http://docs.oasis-open.org/odata/odata/v4.01/cs01/part1-protocol/odata-v4.01-cs01-part1-protocol.html#sec_BatchRequests). **Please be aware that the try it out functionality is not supported** for this request.
      parameters:
        - name: Host
          in: header
          type: string
          description: Host URL of the service
        - name: Content-Type
          in: header
          type: string
          required: true
          description: Payload Content-Type, e. g. multipart/mixed;boundary=batch_36522ad7-fc75-4b56-8c71-56071383e77b
        - in: body
          name: payload
          schema:
            type: string
            example: |
             --batch_36522ad7-fc75-4b56-8c71-56071383e77b
              Content-Type: application/http 
              
              GET /service/Customers('ALFKI') 
              Host: host
              
              
              --batch_36522ad7-fc75-4b56-8c71-56071383e77b 
              Content-Type: application/http 
              
              GET /service/Products HTTP/1.1 
              Host: host 
              
              
              --batch_36522ad7-fc75-4b56-8c71-56071383e77b--
      responses:
        202:
          description: Batch request accepted
        default:
          $ref: '#/responses/error'

[ralfhandl]

@fbunsmann and @Tiberriver256 please have a look at this example with /$batch: does that meet your requirements?

Added an example for Swagger 2.0 with /$batch - here "Try it out" actually works.

[ralfhandl]

Opened issue for Swagger UI to find out how to get OpenAPI 3.0 example working: swagger-api/swagger-ui#5090

[Tiberriver256]

Yes! That looks excellent. Thank you!

[fbunsmann]

Also think that looks really good. Thanks Ralf!

[ralfhandl]

Transformation now produces /$batch path items, see e.g. TripPin example