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 :-/
Related
I have an endpoint which returns an image in response and I would like the swagger documentation to return and display the image within the framework.
I've looked at the documentation here and here and tried all three examples all which have no success.
Am I trying the impossible?
Here is my example
paths:
"/qrcodes/{string_to_encode}":
get:
tags:
- QR Code
summary: A QR code generation endpoint
parameters:
- name: string_to_encode
in: path
required: true
description: URL encoded string to convert to a QR code
schema:
type: string
responses:
'200':
description: OK
content:
application/png:
schema:
type: string
format: binary
The generated curl also warns about binary output
Change application/png to image/png. Other than that, your definition is correct.
I'm writing a Swagger definition on swaggerhub. There's an option to share models among multiple Swaggers. After swaggers are complete there's an option to download resolved Swagger with the linked definitions imported.
My problem is that this resolved download adds a example node to the models which for whatever reason overrides every attribute when we copy this new Swagger in editor again.
Suppose we have following sample
---
swagger: "2.0"
info:
description: ""
version: 1.0.0
title: title
host: "example.com"
basePath: /
schemes:
- http
consumes:
- application/json
produces:
- application/json
paths:
/test-service:
post:
tags:
- test-service
operationId: test-service
parameters:
- in: body
name: body
description: body
required: true
schema:
$ref: '#/definitions/A'
responses:
201:
description: success
schema:
$ref: '#/definitions/A'
definitions:
A:
type: object
properties:
a1:
type: string
a2:
type: string
Following is how it's displayed in the Swagger UI,
This is correct way, however when I there's an example node in the model A, only example attributes are displayed in the UI,
Here's the change that that I'm referring to
A:
type: object
properties:
a1:
type: string
a2:
type: string
example:
ex1: Hello
ex2: World
Now, if I import this change in the editor, only attributes ex1 and ex2 and actual attributes a1 and a2 are missing.
Problem is exacerbate when we have inheritance.
What happens is whichever lowest node in hierarchy has example attribute only attributes listed in that are shown in the UI, rather than showing all attributes
Here's a sample wi
Now lets introduce example attribute in C. After addition of example attribute at any level all other attributes are ignored.
Here's the link to example attribute documentation https://swagger.io/docs/specification/2-0/adding-examples/.
There's no description of this weird behavior.
That's how example works. Quoting the OpenAPI 2.0 Specification:
A free-form ... example of an instance for this schema.
That is, example is an example for the entire schema. That's why a schema-level example is displayed as is. It overrides any property-level examples, and won't automatically include properties that aren't included in the example.
In your last example with allOf, the schema for A is equivalent to
definitions:
A:
type: object
properties:
a1:
type: string
a2:
type: string
b1:
type: string
b2:
type: string
c1:
type: string
c2:
type: string
example:
ex1: Hello
ex2: world
which again is why the schema-level example from C overrides everything else.
You might want to use property-level examples instead:
definitions:
A:
type: object
properties:
a1:
type: string
example: Hello # <---
a2:
type: string
example: world # <---
I have a swagger file for an API that is going to reside inside IBM API Connect. I typed it out from an IBM tutorial, and I was trying to replicate what the instructor was doing(he did not provide any source files, so I had to type it out).
The tutorial is available here: https://www.youtube.com/watch?v=hCvUYd67rbI
The guy is copy-pasting the swagger file inside the APIConnect local designer around 21:40.
I took the swagger file and put it into http://editor.swagger.io/ and I got a bunch of parser errors:
Errors
Hide
Parser error duplicated mapping key
Jump to line 31
Semantic error at definitions.shipping.properties.xyz.type
Sibling values are not allowed alongside $refs
Jump to line 86
Semantic error at definitions.shipping.properties.cek.type
Sibling values are not allowed alongside $refs
Jump to line 89
I did some digging, and I did not find a lot of resources for my kind of problem. I double-checked if I typed it out correctly from the tutorial. Maybe it has something to do with an older version of API Connect being used in ths tutorial.
Thanks in advance for anyone who can help.
EDIT:
Sorry, it was a bit late so I was tired, I am adding the source code in the yaml file:
info:
x-ibm-name: logistics
title: logistics
version: 1.0.0
schemes:
- https
basePath: /logistics
consumes:
- application/json
produces:
- application/json
securityDefinitions:
clientIdHeader:
type: apiKey
in: header
name: X-IBM-Client-Id
security:
- clientdHeader: []
x-ibm-configuration:
testable: true
enforced: true
cors:
enabled: true
gateway: datapower-gateway
catalogs:
apic-dev:
properties:
runtime-url: $(TARGET_URL)
properties:
shipping_svc_url:
value: 'http://shipping.think.ibm:5000/calculate'
description: Location of the shipping calculator service
encoded: false
paths:
/shipping:
get:
responses:
'200':
description: 200 OK
schema:
$ref: '#/definitions/shipping'
summary: Calculate shipping costs to a destination zip code
operationId: shipping.calc
parameters:
- name: zip
type: string
required: true
in: query
description: Destination zip code.
/stores:
get:
responses:
'200':
description: 200 OK
schema:
$ref: '#/definitions/store_location'
tags:
- stores
summary: Locate store near zip code
operationId: get.stores
parameters:
- name: zip
type: string
required: true
in: query
definitions:
rates:
properties:
next_day:
type: string
example: '20.00'
two_day:
type: string
example: '17.00'
ground:
type: string
example: '8.00'
required:
- two_day
- next_day
- ground
shipping:
properties:
xyz:
type: string
$ref: '#/definitions/rates'
cek:
type: string
$ref: '#/definitions/rates'
required:
- xyz
- cek
store_location:
properties:
google_maps_link:
type: string
example: 'https://www.google.com/maps?q=34.1030032,-118.4104684'
required:
- google_maps_link
There's typo: securityDefinitions defines clientIdHeader, but security refers to clientdHeader (..ntd.. instead of ..enId..).
"Sibling values are not allowed alongside $refs" is not a syntax error, but rather a warning. It's caused by this line:
definitions:
rates:
properties:
...
shipping:
properties:
xyz:
type: string # <---------------
$ref: '#/definitions/rates'
$ref is a JSON Reference, it works by replacing itself and all sibling attributes with the content the $ref is pointing at. So, the type attribute and any other attributes alongside $ref will be ignored. The warning informs you about this in case there are important attributes alongside $ref -- these attributes need to be moved into the $ref'erenced schema to have effect.
That said, xyz being type: string does not make sense, because rates is an object and not a string.
You should also consider adding type: object to the rates, shipping and store_location definitions to indicate that they are objects.
I'm attempting to document a REST API using Swagger. Per REST API norms, I have endpoints for each Thing, and the GET protocols for each endpoint are bog standard normal: /thing/{id} returns a single Thing with the matching ID you give, and /thing/ returns a list of all valid Things.
The YAML for /thing/{id} is straightforward enough.
get:
operationId: GET_thing-id
tags:
- Thing
description: >-
Gets a specific Thing.
parameters:
- name: token
in: query
required: false
type: string
- name: Accept
in: header
required: false
type: string
responses:
'200':
description: ''
schema:
$ref: '#/definitions/Thing'
Where the $ref refers to the following, further down the YAML file:
definitions:
Thing:
title: Thing
type: object
properties:
id:
type: string
description: uuid.
But I find myself unsure how to handle the /thing/ endpoint, which is supposed to simply return a list of the models above. There seems to be no clear way to do this from perusing the Swagger spec, which I have done in depth at this point. Does anyone have guidance on how to handle this?
I figured it out. The problem was that there's slightly different things I need to define for an array and that was a real issue in tracking it down. The solution is:
definitions:
ThingArray:
title: ThingArray
type: array
items:
$ref: '#/definitions/Thing'
This can then be used in the /thing/ path and it looks perfectly reasonable.
I'm trying to write a simple Swagger / Open API definition using the Swagger Editor.
swagger: "2.0"
info:
version: 1.0.0
title: Test API
description: Test API
schemes:
- https
host: hipaa.ai
basePath: /v1
paths:
/comments:
post:
summary: Your comments
description: Comments
parameters:
- name: text
in: body
description: An array of text strings
type: array
minItems: 1
maxItems: 1000
items:
type: text
I'm getting the following error:
Schema error at paths./comments.post.parameters[0]
is not exactly one from <#/definitions/parameter>,<#/definitions/jsonReference>
I've checked the Swagger schema reference, and the petstore example, but I'm not sure why I'm getting this. Any ideas?
Body parameters use the schema keyword to specify the type, so you need to move type, items, minItems and maxItems under schema.
Also, type: text is not a valid type. Use type: string instead.
parameters:
- name: text
in: body
description: An array of text strings
schema:
type: array
minItems: 1
maxItems: 1000
items:
type: string