Forum Discussion

bhaveshj21's avatar
bhaveshj21
New Contributor
6 years ago

creating swagger api spec for multipart batch request

I need to create swagger api spec for a multipart batch request and response, which allow me to define the request and response format as well as validate them, the request and response look like these 

 

request 

POST /example/application HTTP/1.1
    Host: example.org
    Content-Type: multipart/batch;
      type="application/http;version=1.1";
      boundary=batch
    Mime-Version: 1.0

    --batch
    Content-Type: application/http;version=1.1
    Content-Transfer-Encoding: binary
    Content-ID: <df536860-34f9-11de-b418-0800200c9a66@example.org>

    POST /example/application HTTP/1.1
    Host: example.org
    Content-Type: text/plain
    Content-Length: 3

    Foo
    --batch
    Content-Type: application/http;version=1.1
    Content-Transfer-Encoding: binary
    Content-ID: <226e35d0-34fa-11de-b418-0800200c9a66@example.org>

    PUT /example/application/resource HTTP/1.1
    Host: example.org
    Content-Type: image/jpg
    Content-Length: 123456

    {jpg image data}
    --batch--

 response

    HTTP/1.1 200 OK
    Date: Wed, 29 Apr 2009 20:00:00 GMT
    Server: example.org
    Content-Type: multipart/batch;
      type="application/http;type=1.1";
      boundary=batch
    Mime-Version: 1.0

    --batch
    Content-Type: application/http;version=1.1
    Content-Transfer-Encoding: binary
    In-Reply-To: <df536860-34f9-11de-b418-0800200c9a66@example.org>

    HTTP/1.1 204 OK
    Date: Wed, 29 Apr 2009 20:00:00 GMT
    Server: example.org

    --batch
    Content-Type: application/http;version=1.1
    Content-Transfer-Encoding: binary
    In-Reply-To: <226e35d0-34fa-11de-b418-0800200c9a66@example.org>

    HTTP/1.1 415 Unsupported Media Type
    Date: Wed, 29 Apr 2009 20:00:00 GMT
    Server: example.org

    --batch--

 I got something like this 

openapi: 3.0.0
info:
  title: $batch example
  version: ''
  description: This is a sketch for $batch
servers:
  - url: 'https://services.odata.org/V4/(S(cnbm44wtbc1v5bgrlek5lpcc))/TripPinServiceRW'
tags:
  - name: Batch Requests
paths:
  /$batch:
    post:
      summary: Send a group of requests
      description: |-
        Group multiple requests into a single request payload, see [OData Batch Requests](http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_BatchRequests).


        *Please note that "Try it out" is not supported for this request.*
      tags:
        - Batch Requests
      requestBody:
        required: true
        description: Batch request
        content:
          multipart/mixed;boundary=request-separator:
            schema:
              type: string
            example: |-
              --request-separator
              Content-Type: application/http
              Content-Transfer-Encoding: binary

              GET http://services.odata.org/V4/(S(cnbm44wtbc1v5bgrlek5lpcc))/TripPinServiceRW/People HTTP/1.1
              Accept: application/json


              --request-separator--
      responses:
        '202':
          description: Batch response
          content:
            multipart/mixed:
              schema:
                type: string
              example: |-
                --response-separator
                Content-Type: application/http

                HTTP/1.1 200 OK
                Content-Type: application/json

                {"value":[...]}
                --response-separator--
        default:
          $ref: '#/components/responses/error'
components:
  schemas:
    odata.error:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/odata.error.main'
    odata.error.main:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string
        target:
          type: string
        details:
          type: array
          items:
            $ref: '#/components/schemas/odata.error.detail'
        innererror:
          type: object
          description: The structure of this object is service-specific
    odata.error.detail:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string
        target:
          type: string
  parameters:
    top:
      name: $top
      in: query
      description: 'Show only the first n items, see [OData Paging - Top](http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_SystemQueryOptiontop)'
      schema:
        type: integer
        minimum: 0
      example: 50
    skip:
      name: $skip
      in: query
      description: 'Skip the first n items, see [OData Paging - Skip](http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_SystemQueryOptionskip)'
      schema:
        type: integer
        minimum: 0
    count:
      name: $count
      in: query
      description: 'Include count of items, see [OData Count](http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_SystemQueryOptioncount)'
      schema:
        type: boolean
    search:
      name: $search
      in: query
      description: 'Search items by search phrases, see [OData Searching](http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_SystemQueryOptionsearch)'
      schema:
        type: string
  responses:
    error:
      description: Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/odata.error'

here they have specified the batch request format in the example , is there some other way of doing it like specifying it in parameters and from which I can validate the request and response through swagger.

2 Replies

  • There is a way to describe multipart requests in more details in OAS3, you can find information about it in the documentation.

     

    Keep in mind that support in tooling (ours and others) is going to be limited for multipart, especially batch, as it is not a very common practice in APIs.

    • bhaveshj21's avatar
      bhaveshj21
      New Contributor

      ya already gone through this , was looking if there some thing else availabe, thanks.