CODEWITHSUNDEEP
restjsonschemaswagger-uiswagger-2.0swagger-editor
g0c00l.g33k
g0c00l.g33k

Reputation: 2618

Open API POST with Path Parameter

I am trying to write a Open API specification with Swagger-ui (swagger version 2.0) and I am not sure how to represent a POST parameter with a path parameter

POST /ping/{text}

My specification is as follows,

# this is an example of the Uber API
# as a demonstration of an API spec in YAML
swagger: '2.0'
info:
  title: Mock API
  description: Mock API 
  version: "1.0.0"
# the domain of the service
host: api.mock.com
# array of all schemes that your API supports
schemes:
  - https
# will be prefixed to all paths
basePath: /v1
produces:
  - application/json
paths:
  /ping:
    get:
      summary: Ping
      description: |
        Respond to PING requests, similar to heart beat
      parameters:
        - name: path  
          in: path
          description: String input for echo service
          required: false
          type: string
      tags:
        - ping
      responses:
        200:
          description: The text passed in the request
          schema:
            type: string
        default:
          description: Empty response for request passed
          schema:
            type: string

And the swagger ui shows an error as follows -

 code:  "ONE_OF_MISSING"
 message:  "Not a valid parameter definition"

but if I change it to in: query the error vanishes. What am I doing wrong? or what is the right way to specify a path parameter in open API specification?

Upvotes: 1

Views: 7361

Answers (2)

Navid Shakibapour
Navid Shakibapour

Reputation: 555

There are a few changes you need to make to your document to conform to the Open API specification.

1- The name field should match the path segment (ie text

If in is "path", the name field MUST correspond to the associated path segment from the path field in the Paths Object. See Path Templating for further information.

2- required: true should be added.

If the parameter is in "path", this property is required and its value MUST be true.

3- If you want to document POST /ping/{text}, get needs to be changed to post. Also the path segment (ie. /{text) should be added to the path.

Here is the final Swagger doc after the changes described above:

# this is an example of the Uber API
# as a demonstration of an API spec in YAML
swagger: '2.0'
info:
  title: Mock API
  description: Mock API 
  version: "1.0.0"
# the domain of the service
host: api.mock.com
# array of all schemes that your API supports
schemes:
  - https
# will be prefixed to all paths
basePath: /v1
produces:
  - application/json
paths:
  /ping/{text}:
    post:
      summary: Ping
      description: |
        Respond to PING requests, similar to heart beat
      parameters:
        - name: text  
          in: path
          description: String input for echo service
          required: true
          type: string
      tags:
        - ping
      responses:
        200:
          description: The text passed in the request
          schema:
            type: string
        default:
          description: Empty response for request passed
          schema:
            type: string

Upvotes: 1

Daniel
Daniel

Reputation: 911

According to the specification it seems that "required" has to be true if you set "in: path".

Details can be found here: http://swagger.io/specification/#parameterObject

Upvotes: 1

Related Questions