bhaveshj21
7 years agoNew Contributor
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.