my conf looks something like:
swagger: "2.0"
info:
version: "1.0.0"
title: "Users API"
definitions:
Users:
type: 'string'
enum: &USERS [...huge list...]
...
- in: "formData"
name: "users"
description: "Can search for these usernames"
enum: *USERS
...
The issue in the UI is that I have a very long / non-readable list under Available Values:..... list of all *USERS ....
I can't seem to find in the docs how to hide, anyone know ?
Related
When I add examples into my swagger doc and test it on the swagger editor, then it never shows anywhere. Could someone give me an example of where multiple examples are actually showing anywhere?
Here is an example of how multiple examples are added:
it is from: https://swagger.io/docs/specification/adding-examples/
Here is an example of yaml that does not display any examples on the online swagger editor:
openapi: 3.0.0
info:
title: Some API
version: 1.0.0
paths:
/logon:
get:
summary: Login user
tags:
- '/logon'
parameters:
- name: Client
in: query
required: true
examples:
zero:
value: '0'
summary: A sample limit value
max:
value: '50'
summary: A sample limit value
schema:
type: string
responses:
'200':
description: Success response
Multiple examples are displayed in Swagger UI 3.23.0+ and Swagger Editor 3.6.21+:
In older versions, you can use a single example as a workaround:
parameters:
- name: Client
in: query
required: true
example: '50' # <-----
schema:
type: string
I'm using http://editor.swagger.io to design an API and I get an error which I don't know how to address:
Schema error at paths['/employees/{employeeId}/roles'].get.parameters[0]
should NOT have additional properties
additionalProperty: type, format, name, in, description
Jump to line 24
I have other endpoints defined in a similar way, and don't get this error. I wondered if I had some issue with indentation or unclosed quotes, but that doesn't seem to be the case. Google also did not seem to provide any useful results.
swagger: "2.0"
info:
description: Initial draft of the API specification
version: '1.0'
title: App 4.0 API
host: api.com
basePath: /v1
tags:
- name: employees
description: Employee management
schemes:
- https
paths:
/employees/{employeeId}/roles:
get:
tags:
- employees
summary: "Get a specific employee's roles"
description: ''
operationId: findEmployeeRoles
produces:
- application/json
parameters:
- name: employeeId <====== Line 24
in: path
description: Id of employee whose roles we are fetching
type: integer
format: int64
responses:
'200':
description: successful operation
schema:
type: array
items:
$ref: '#/definitions/Role'
'403':
description: No permission to see employee roles
'404':
description: EmployeeId not found
Any Hints?
The error message is misleading. The actual error is that your path parameter is missing required: true. Path parameters are always required, so remember to add required: true to them.
Had the same problem. I accidentally mixed up the syntax from Swagger 2.0 with Openapi 3.0.x. In Openapi 3.0.x, definitions are redefined as components. In the online editor you can click on the button Edit > Convert to OpenAPI 3 to use Openapi 3.0.x.
Read more about components here.
Remark:
OAS 3 is the latest version of the
OpenAPI Specification.
For me the cause of the error was a missing a leading slash in the path (internal/resource instead of /internal/resource).
And yes the error message is extremely unhelpful.
In my case I was missing parameter definition in api definition
- name: parameterName
in: query
description: parameter's description here.
required: false
schema:
type: string
In my case it had the wrong indentation for the example. It was:
content:
application/json:
schema:
$ref: '#/components/schemas/someresponse'
examples:
example1:
value:
param1: "some string"
param2: "123"
Rather than:
content:
application/json:
schema:
$ref: '#/components/schemas/someresponse'
examples:
example1:
value:
param1: "some string"
param2: "123"
But the VScode open api preview with swaggerUI didn't show any errors and everything looked valid.
The syntax requires might require two parameters, as mentioned by Helen required: true is need so is type:DataType . The error is misleading.
I'm new to Swagger. I've written the following code using Swagger Editor, but I'm getting multiple errors. I've already looked at documentation and other examples, but I'm not able to clarify the problem.
swagger: '2.0'
info:
version: "1"
title: 'Grocery Shop'
description: 'This contains the url to access all the Grocery food related information. You can also add, update or delete any food item as well based on their respective id.'
contact:
email: you#your-company.com
tags:
- name: FoodItem
description: Specifically for Food item
- name: Category
description: Specifically for the category purpose
schemes:
- https
paths:
'/findfood/{foodItemId}':
get:
tags:
- FoodItem
summary: "Find the required food"
description: "Find the food with passed food id as an argument. Make sure that passed id exist otherwise it will return an error"
operationId: findFoodWithId
produces:
- "application/json"
parameters:
- in: path
name: foodItemId
required: true
type: integer
miniumum: 1
description: The id associated with the food in the grocery shop
responses:
200:
description: "successful operation"
schema:
$ref: '#definitions/Food'
404:
description: "Food is not found
definitions:
Food:
type: "object"
properties:
foodItemId:
type: integer
format: int32
required:
- foodItemId
xml:
name: "User"
# Added by API Auto Mocking Plugin
host: "localhost:8080"
basePath: "/grocery"
The errors which I'm getting are:
Semantic error at paths./findfood/{foodItemId} Declared path parameter
"foodItemId" needs to be defined as a path parameter at either the
path or operation level Jump to line 18
Schema error at paths./findfood/{foodItemId}.get.parameters[0] is not
exactly one from
<#/definitions/parameter>,<#/definitions/jsonReference> Jump to line
28
Parser error can not read a block mapping entry; a multiline key may
not be an implicit key Jump to line 48
These errors are misleading. The actual errors are:
miniumum: 1 contains a typo - miniumum
$ref: '#definitions/Food' needs a / between # and definitions: '#/definitions/Food'
description: "Food is not found needs the ending quotation mark.
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
I am using http://editor.swagger.io minimal.yaml example to define a MenuItem which has submenuitem property of type array recursively referencing MenuItem. But I get submenuitem as undefined. Any pointers to what might be wrong ?
---
swagger: '2.0'
info:
version: 0.0.0
title: Simple API
paths:
/:
get:
responses:
200:
description: OK
definitions:
MenuItem:
properties:
submenuitem:
items:
$ref: "#/definitions/MenuItem"
title: SubMenuItem
type: array
display_name:
minLength: 2
title: "Link display name"
type: string