What does the "=" mean within the path parameter of the following OpenApi / Swagger spec?
https://github.com/grafeas/grafeas/blob/master/proto/v1beta1/swagger/grafeas.swagger.json#L18
Here is an excerpt (converted to YAML from JSON for readability):
swagger: '2.0'
info:
title: grafeas.proto
version: version not set
schemes:
- http
- https
consumes:
- application/json
produces:
- application/json
paths:
'/v1beta1/{name=projects/*/notes/*}':
get:
summary: Gets the specified note.
operationId: GetNote
responses:
'200':
description: A successful response.
schema:
$ref: '#/definitions/v1beta1Note'
parameters:
- name: name
description: |-
The name of the note in the form of
`projects/[PROVIDER_ID]/notes/[NOTE_ID]`.
in: path
required: true
type: string
tags:
- GrafeasV1Beta1
The path is defined as /v1beta1/{name=projects/*/notes/*} and a parameter called name is defined, but when I put the whole .json into https://editor.swagger.io, I get errors of the form:
Declared path parameter "name=projects/*/notes/*" needs to be defined
as a path parameter at either the path or operation level
I believe this swagger spec was auto-generated and the =TEXT within the {param} blocks to be an error. I have raised this as https://github.com/grafeas/grafeas/issues/379.
Related
I'm having problems defining custom request headers for my OpenAPI (Swagger) document. I've looked in the documentation https://swagger.io/docs/specification/describing-parameters/#header-parameters but I cannot get it to work.
In my example below is a POST request which has has a body. I also want it to have a custom header like my second snippet, but that is not valid.
This is OK:
/search:
post:
tags:
- Domain
summary: Search for domains
description: Returns a domain if it was found.
produces:
- application/json
parameters:
- in: body
name: body
description: Array of Domain Names
required: true
schema:
$ref: '#/definitions/DomainNames'
This is not OK:
/search:
post:
tags:
- Domain
summary: Search for domains
description: Returns a domain if it was found.
produces:
- application/json
parameters:
- in: header
name: X-Request-ID
schema:
type: string
format: uuid
required: true
- in: body
name: body
description: Array of Domain Names
required: true
schema:
$ref: '#/definitions/DomainNames'
On the - in: header line I get the following error:
Schema error at paths['/search'].post.parameters[0].in
should be equal to one of the allowed values
allowedValues: body, header, formData, query, path
Jump to line 37
Schema error at paths['/search'].post.parameters[0]
should NOT have additional properties
additionalProperty: schema, in, name
Jump to line 37
What am I missing here? The header shows up in the rendered Swagger UI but I can't "Save" it as it is not valid.
The guide you linked to is for OpenAPI 3.0 (as indicated at the top of that page). The corresponding OpenAPI 2.0 guide is here: Describing Parameters.
In OpenAPI 2.0, path/header/query/form parameters do not use schema, they use the type keyword directly.
Also, the - in: header line in your example is not indented enough, you need to add one more space before it to align it with other lines.
Here's the correct version:
parameters:
- in: header # <----
name: X-Request-ID
type: string # <----
format: uuid # <----
required: true
I am creating an OpenAPI (Swagger) definition and checking its validity in http://editor.swagger.io. For some reason, Swagger Editor shows this error:
Schema error at paths['/some-endpoint/{id}/name-and-address'].get.parameters[0]
should NOT have additional properties
additionalProperty: type, allowEmptyValue, enum, name, in, description, required
Jump to line 142
Below is my YAML file:
paths:
'/some-endpoint/{id}/name-and-address':
get:
tags:
- InvolvedParty
summary: Retrieve basic information about...
operationId: getNameAndAddressUsingGET
produces:
- '*/*'
parameters:
- name: id
in: path
description: The unique identification
required: true
type: string
allowEmptyValue: false
enum:
- '#coderange[1'
- 'infinity]'
responses:
'200':
description: Success
I haven't added any other properties as the error message implies. How to fix this error?
Remove allowEmptyValue - it's only used with query and formData parameters, but not with path parameters.
How do I set a content type other than application/json for a body parameter in Swagger UI 3.x using a Swagger (Open API) 2.0 YAML definition file?
My YAML file is as follows, with the consumes element set to application/json+fhir and application/xml+fhir:
swagger: '2.0'
info:
title: Test
version: '1.0'
host: 'server.com'
basePath: /fhir
schemes:
- http
paths:
/Patient/$getrecordsection:
post:
tags:
- Get record section
summary: Retrieve a care record section
consumes:
- application/json+fhir
- application/xml+fhir
produces:
- application/json+fhir
- application/xml+fhir
parameters:
- in: body
name: body
description: ''
required: true
schema:
$ref: '#/definitions/GetRecordSection'
responses:
'200':
description: OK
'400':
description: Bad request
definitions:
GetRecordSection:
type: object
properties:
resourceType:
type: string
default: "Parameters"
parameter:
type: string
example:
resourceType: "Parameters"
parameter:
- name: "patientIdentifier"
valueIdentifier:
system: "http://fhir.provider.net/Id/patient-identifier"
value: "9999999999"
- name: "recordSection"
valueCodeableConcept:
coding:
- system: "http://fhir.provider.net/ValueSet/record-section"
code: "ALL"
xml:
name: Parameters
However, the Swagger UI only shows application/json as the body parameter content type:
I'm using the current latest Swagger UI build - 3.11.0.
This is a problem with Swagger UI, rather than the Swagger Editor (though I know the two share a significant number of components), and so the root cause could be the same.
This is a bug in the 3.11.0 version of Swagger UI, using Swagger/Open API 2.0:
https://github.com/swagger-api/swagger-ui/issues/4257
I'm creating Swagger documentation for an URL that looks like this:
mysite.local.com/mylink?callback&service=someservicename¤cy=USD
As you can see, the callback parameter in the query string has a name but no value. How do I describe this parameter in Swagger?
Here's the YAML code I'm using:
swagger: "2.0"
info:
title: My API
description: Documentation of webservices Used
version: 1.0.0
host: mysite.local.com
basePath: /
schemes:
- https
paths:
/mylink:
get:
summary: sometext
description: Optional extended description in Markdown.
produces:
- application/json
responses:
200:
description: OK
parameters:
callback:
I found in the doc that you can specify a parameter that is in the "query", but i'm pretty sure you'll have to give it a value (ie : ?callback=true)
Example :
paths:
/mylink:
get:
summary: sometext
description: Optional extended description in Markdown.
produces:
- application/json
responses:
200:
description: OK
parameters:
- name: callback
in: query
type: boolean
I am starting a REST service, using Swagger Codegen. I need to have different responses for different parameters.
Example: <baseURL>/path can use ?filter1= or ?filter2=, and these parameters should produce different response messages.
I want my OpenAPI YAML file to document these two query params separately. Is this possible?
It is not supported in the 2.0 spec, and not in 3.0 either.
Here are the corresponding proposals in the OpenAPI Specification repository:
Accommodate legacy APIs by allowing query parameters in the path
Querystring in Path Specification
If you're still looking, I found out a way around this problem. It's a bit of a hack, but it works.
Basically, you can have two definitions to the same path by adding a slash (/) in the URL.
That way, you can set a response for <baseURL>/path with the ?filter1= parameter and set another response for <baseURL>//path with the ?filter2= parameter. It's also important that you give an unique operationId for each of the definitions.
paths:
/path/you/want:
get:
summary: Test
operationId: get1
parameters:
- name: filter1
type: string
in: path
required: true
responses:
200:
description: Successful response
schema:
$ref: '#/definitions/SomeResponse'
/path/you//want:
get:
summary: Another test
operationId: get2
parameters:
- name: filter2
type: string
in: path
required: true
responses:
200:
description: Successful response
schema:
$ref: '#/definitions/SomeOtherResponse'
I tried this with a path parameter and it worked just fine!
In swagger defining location,type explicitly is what defines these variables.
You have all the required fields to avoid collision of variables, for a json body you have to reference a declaration or use an example schema as shown below. For my case I have used a schema example rather than a declaration reference
/auth/account/password/reset/{userId}/{resetToken}:
post:
consumes:
- application/json
parameters:
- in: path
name: userId
type: string
required: true
- in: path
type: string
name: resetToken
required: true
- in: header
name: authorization
required: true
type: string
- in: body
name: body
required: true
schema:
type: object
example:
password: password
confirmPassword: password
responses:
"200":
description: OK
In Swagger you can add ? to make endpoints different.
i.e. /articles and /articles?:
When using ? in Swagger editor you will see error:
However on your final Swagger page there will be mark VALID
Additional information:
Remember about unique operationId for duplicated entries