If I'm describing "public byte[] Data" I do so as:
Data:
type: string
format: base64
description: "The generated report as a single file in the user specified format. If this is populated Pages will be null."
But how do I describe a 2 dimensional array like "public byte[][] Pages"?
Usually multidimensional array is used for Request component but for the Response component the array will be flatted as single array of bytes.
Anyway you could achieve with the following code :
Data:
type: array
items:
type: string
format: base64
description: "The generated report as a single file in the user specified format."
Related
Is it possible to declare a parameter in an OpeanApi 3 schema as being "data URL"? If I understand the specification, the format can be basically anything, but should I use some specific format or should I just do it like this?
MyObject:
title: MyObject
description: Information about my object
type: object
required:
- myData
properties:
myData:
type: string
format: data URL
You can define a data URL as a string
I'm importing a swagger openapi 3.0.0 file in Postman. I have some example data in swagger that I'd like to be synchronized in the postman collection.
Example of example data:
RestaurantPayload:
type: object
properties:
google_places_id:
type: number
format: integer
name:
type: string
city:
type: string
cover_image:
type: string
latitude:
type: number
format: double
longitude:
type: number
format: double
rating:
type: number
format: float
categories:
type: array
items:
type: string
example:
google_places_id: 561
name: "Very cool restaurant"
city: "Rome"
cover_image: "http://my-picture-url.jpg"
latitude: 39.485855
longitude: 49.48585747
rating: 4
categories: [
"sushi"]
I tried three different ways:
1- Importing the JSON/YAML as it's exported from swagger directly in Postman. It works and I get the collection with all the methods I'm looking for BUT I'm missing example data. For instance
2- Converting the openapi file to postman using the postman command line converter (https://github.com/postmanlabs/openapi-to-postman)
Same situation, example data is missing
3- Using an external service as APImatic (https://www.apimatic.io)
This is the only way I managed to get a Postman JSON which - once imported in the postman app - keeps all example data in place
I'd really like NOT to need an external service to perform this task and to be able instead to translate my openapi specifications to postman with all the example data with a command line tool or something similar.
Do you happen to know why is this happening and how I can get what I need?
Thank you
Marco
Edit: the APImatic solution doesn't seem to be viable because it breaks the endpoints.
APImatic:
YAML import from Swagger
So I'm stuck, one import method breaks the endpoints while the other breaks the examples :-/
I'm using Swagger Editor with OpenAPI 3.0. I need to document a route which consists of uploading an image. When attempting to "Try it out", I don't get the file browser to choose the image to upload in the request body, all I get is a JSON string with the name and type of parameter.
This is the YAML description of the route:
openapi: 3.0.0
...
paths:
/media/upload/thumbnail:
post:
tags:
- media
- publications
security:
- bearerAuth: []
summary: upload a kid's publication
operationId: uploadPublication
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
upload:
type: string
format: binary
responses:
'200':
description: Successful operation
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: ObjectId of the uploaded file in db (original size)
example: 5a6048b3fad06019afe44f24
filename:
type: string
example: myPainting.png
thumbnail:
type: string
description: ObjectId of the uploaded file in db (thumbnai size)
example: 5a6048b3fad06019afe44f26
'400':
description: Authentication failed
What am I missing here?
Your definition is correct.
Support for file upload for multipart/form-data requests in OpenAPI 3.0 definitions has been added in Swagger Editor 3.5.7 and Swagger UI 3.16.0. Make sure you are using a version that supports file upload.
For one of my same kind of concern !!!
I had to modify the input type to requested endpoint method.
Note- It might not address all type of requirements, but few can definitely be benefitted from this
Before:
/myEndpoint( #RequestBody RequestModelName requestModelName )
where RequestModelName has properties and getter/setter...
private MultipartFile file
private String otherProp
By this I could NOT see File option in swagger.
After:
/myEndpoint( #RequestParam MultipartFile file, #RequestParam String otherProp )
And then I could see File option in swagger...
Try with
content:
image/png:
schema:
properties:
file:
type: string
format: binary
Seem to almost have it...
Trying to have swagger send an anonymous hash of parameters in the request body.
I have an anonymous hash containing one key named list that contains an array.
Trying to send this parameter (text/json):
{
list : [ 'string1', 'string2' ]
}
Swagger is building the right curl statement but is not sending the parameters via the UI.
Swagger builds this (works from command line):
/usr/bin/curl -H 'Content-Type: text/json' -X GET -d '{ "list" : [ "text:/export/home/ihome/perl5/our_modules/check_parse_lib_rest/t/data/hosts:/export/home/ihome/perl5/our_modules/check_parse_lib_rest/t/data/hosts", "text:/export/home/ihome/perl5/our_modules/check_parse_lib_rest/t/data/hosts:/export/home/ihome/perl5/our_modules/check_parse_lib_rest/t/data/hosts.1" ] }' 'https://localhost.localdomain:9086/library/check_diff_batch'
But Swagger-ui shows no model example and sends no parameters in the request body.
In the editor I see it the list shows as undefined.
Schema
⇄
Comparison {
list:
ComparisonList undefined *
}
Definition -
paths:
/check_diff_batch:
get:
summary: Compare a list of file comparrison objects using diff.
description: |
FIXME: Takes an array of colon delimited comparrison objects.
Required parameter Comparrison object format = type:file1:file2
**RC** will return false if there are differences or a failure.
**FAULT_MSG** will return No Faults or a failure message.
parameters:
- $ref: "#/parameters/ComparrisonList"
responses:
200:
description: Successful response
examples:
text/json:
...
parameters:
ComparrisonList:
name: list
in: body
description: List of comparrison objects
schema:
$ref: "#/definitions/Comparisons"
definitions:
Comparisons:
required:
- list
properties:
list:
$ref: "#/definitions/ComparisonList"
ComparisonList:
additionalProperties:
type: string
additionalProperties is used to define associative arrays / hashmaps, not regular arrays. A regular string array is defined as:
definitions:
ComparisonList:
type: array
items:
type: string
You should also use a post operation and not get, since request body in GET does not have defined semantics as per RFC 7231 section 4.3.1.
I have a GET route where I would like to encode an object parameter in the url as a query string.
When writing the swagger documentation I basically get errors that disallow me to use schema/object types in a query type parameter:
paths:
/mypath/:
get:
parameters
- in: path
name: someParam
description: some param that works
required: true
type: string
format: timeuuid #good param, works well
- $ref: "#/parameters/mySortingParam" #this yields an error
parameters:
mySortingParam
name: paging
in: query
description: Holds various paging attributes
required: false
schema:
type: object
properties:
pageSize:
type: number
cursor:
type: object
properties:
after:
type: string
format: string
The request query param having an object value would be encoded in an actual request.
Even though swagger shows an error at the top of the screen the object is rendered correctly in the swagger UI editor, however with that error floating on top of the documentation.
I don't think you can use "object" as query parameter in Swagger spec as query parameter only supports primitive type (https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types)
This is now possible with OpenAPI 3.0.
parameters:
- in: query
name: values
schema:
type: object
properties:
genre_id:
type: integer
author_id:
type: integer
title:
type: string
example:
{
"genre_id": 1,
"author_id": 1
}
style: form
explode: true
Here you can use style and explode keywords to specify how parameters should be serialised.
style defines how multiple values are delimited. Possible styles depend on the parameter location – path, query, header or cookie.
explode (true/false) specifies whether arrays and objects should
generate separate parameters for each array item or object property.
For the above example the url will be:
https://ebookstore.build/v1/users/books/search?genre_id=1&author_id=1
For more information on describing parameters with OpenAPI v3 and parameter serialisation, please refer here.
This is possible, just not with OpenAPI 2.0. OpenAPI 3.0 describes how this is possible here:
https://swagger.io/docs/specification/describing-parameters/
parameters:
- in: query
name: filter
# Wrap 'schema' into 'content.<media-type>'
content:
application/json: # <---- media type indicates how to serialize / deserialize the parameter content
schema:
type: object
properties:
type:
type: string
color:
type: string
In the meantime you could just have the query parameter as a plain old string type and then perform the serialization manually, then set the query parameter as required. This is what I'm doing until Swagger UI fully supports OpenAPI 3.0.