Open API POST with Path Parameter

Question

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?

Answer 1

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