Designing an API using editor.swagger.io I find myself unable to add a requestBody attribute, getting an error I cannot address:
Schema error at paths['/projects/{projectId}/user'].post
should NOT have additional properties
additionalProperty: requestBody
Jump to line 91
I don't understand what I'm doing wrong, especially after looking at the requestBody documentation. Research has brought me nothing other than the tendency for errors to be misleading.
EDIT: From what the answers here have shown, it looks like the editor is supposed to use OpenAPI 2.0, but actually expects 3.0 while returning errors for both. I'd use some help on what to use, given that I've included a
swagger: "2.0"
line at the beginning of the document.
While testing with openapi: 3.0.0 as shown by #Mike in his answer, I just get more errors about allowed additional properties.
Here's what's generating the error, line 91 being post: .
/projects/{projectId}/user:
post:
tags:
- projects
summary: Modify project user.
operationId: modifyProjectUser
parameters:
- name: projectId
in: path
description: ID of the project
required: true
type: integer
format: int32
requestBody:
content:
application/json:
schema:
$ref: '#/definitions/User'
responses:
"200":
description: Successful operation
schema:
type: array
items:
$ref: "#/definitions/User"
security:
- api_key: []
I got clarifications from an external source, so here's what I've learned:
Specifying swagger: 2.0 also means that the OpenAPI Specification 2.0.0 is expected by the editor, whereas I thought it used OAS 3.
I'm still unsure about why in: body did not work in the first place but I've added quotes around "body", which made the error disappear. Then I tried removing the quotes and it worked fine.
The editor doesn't seem very reliable when it comes to error reporting.
This error message looked familiar. Try inserting a schema: underneath your parameter's required: line, then indent the type: and format: lines.
Since I have not yet set up my own SwaggerUI server. I took your code snippet and pasted it into SwaggerHub. Then I removed the $ref: lines just to further simplify the codebase. Here's a screenshot of the error-free result.
In my case since I was using openapi: 3.0.0. The schema $ref should be '#/components/schemas/{schemaname}' instead of '#/definitions/schemas/{schemaname}'
Related
I try to organize my one giant OpenAPI yaml file into several small pieces and then bundle it with swagger-cli. And I run into the paths section.
This is my openapi.yml file now:
openapi: "3.0.0"
info:
version: 1.0.0
title: Swagger Petstore
description: Multi-file boilerplate for OpenAPI Specification.
license:
name: MIT
servers:
- url: http://example.swagger.io/v1
paths:
/blog:
$ref: './routes/blog/create-getall.yml'
/blog/{id}:
$ref: './routes/blog/show-update-delete.yml'
Now the problem is I want to separate create-getall.yml file into create.yml and get-all.yml, and I want to split show-update-delete.yml file into show.yml, update.yml and delete.yml files.
But after I do this split, I try to use files as reference like this:
paths:
/blog:
$ref: './routes/blog/create.yml'
$ref: './routes/blog/get-all.yml'
/blog/{id}:
$ref: './routes/blog/with-id.yml'
And I get Map keys must be unique error message.
If I try $ref1, $ref2 and similar, then I get Property $ref1 is not allowed error.
I tried to use allOf, but it leads to Property allOf is not allowed. error.
The create.yml file is this:
post:
tags:
- blog
summary: create a blog post
description: |
You can create a new blog post.
parameters:
- in: body
name: content
schema:
$ref: 'Post.yml'
responses:
200:
description: new item's ID
So how can I use these splitted files in paths section?
OpenAPI Specification does not have a way to use multiple $refs under a single path. There's an existing feature request to allow $refs on the operation level which, if implemented, would support your scenario.
I'm encountering a really weird bug in swagger.
When trying to render a component with a property called 'entries', the compiler breaks with the error:
The provided definition does not specify a valid version field.
Please indicate a valid Swagger or OpenAPI version field.
Supported version fields are swagger: "2.0" and those that
match openapi: 3.0.n (for example, openapi: 3.0.0).
An example that will return this error:
openapi: 3.0.2
info:
title: API Documentation
version: '1'
paths:
/v1/detail/:
get:
tags:
- clips
summary: Get details
operationId: Create Detail
description: Retrieve details
parameters: []
responses:
'200':
content:
application/json:
schema:
type: object
$ref: '#/components/schemas/Clip'
description: ''
components:
schemas:
Clip:
type: object
properties:
entries:
type: string
example: 'abc'
But by renaming entries to something else, like 'x_entries', the compiler is OK.
I couldn't find any reference to 'entries' in the openapi documentation, although I could be wrong here. Does anyone know why 'entries' as an property in a component causes an issue?
It was a bug in Swagger UI v. 3.25.3 and Swagger Editor v. 3.8.3.
Fixed in UI v. 3.25.4 and Editor v. 3.9.0.
I am creating a well-organized OAS3 swagger documentation on swaggerhub. For every endpoint i am writing all possible answers like 200, 201, 204, 400, 401, 403, 404, 500 etc. In addition all methods have default parameters like X-Language-Code etc.
I am in such a place that the responses, models, parameters I use now begin to repeat themselves in each file. After a little research i learnt that i can create a domain and remote absolute url references to them.
There is no error when i used the 'definition's remotely like this:
/example:
get:
#some other informations here
responses:
200:
description: 'example description'
content:
application/json:
schema:
$ref: 'https://remote.example/url/2.0#/definitions/ExampleResponse'
But, apparently you can not use $ref keyword right below responses or 400 etc.. keyword like this:
This one not getting error but not rendering the remote reference
responses:
400:
$ref: 'https://remote.example/url/2.0#/responses/Error400'
or this:
This one gives error
responses:
$ref: 'https://remote.example/url/2.0#/responses'
Even, i can not use 'parameters' as i expected:
/example:
get:
parameters:
- languageCode:
$ref: 'https://remote.example/url/2.0#/parameters/languageCode'
/example:
get:
parameters:
- $ref: 'https://remote.example/url/2.0#/parameters/'
I dont want to rewrite all reference definitions below every documentation.
I am confused about using and referencing 'domain's. Can someone explain or referencing a document about this situations since i couldn't found any documentation about it.
Update: OpenAPI 3.0 domains are now supported in SwaggerHub.
As of December 2018, SwaggerHub domains only support the OpenAPI 2.0 syntax but not OpenAPI 3.0. OpenAPI 3.0 and 2.0 use slightly different syntax for parameters, responses, etc., this means you cannot reference an OAS2 domain from an OAS3 API definition.
The workaround is to create another OpenAPI 3.0 API in SwaggerHub and use it as a "domain". You'll need to add a dummy header with openapi: 3.0.0, the info section and empty paths: {} to make the validator happy.
openapi: 3.0.0
info:
title: Common components
version: 1.0.0
paths: {}
# Put your common components here:
components:
schemas:
...
parameters:
...
responses:
...
Then you can reference components from this "domain" using the usual $ref syntax:
$ref: 'https://api.swaggerhub.com/apis/USERNAME/API-NAME/VERSION#/components/responses/Error400'
Make sure the hostname in $refs is API.swaggerhub.com (not APP.swaggerhub.com) and the link contains /apis/ (not /domains/).
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 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.