Dredd: Path parameter examples for swagger

[JefStat]

I cannot figure out how to specify an example value for a path parameter in the swagger definition. After scouring the swagger spec I don't see anyway of adding an example value or where dredd would be expecting to read the example value of a path parameter. The dredd doc suggest that dredd will use a default string in this case for the parameter but instead this error is returned.

error: Compilation error in file 'http://localhost:8800/swagger/v1/swagger.json': Required URI parameter 'id' has no example value. (Events > /events/{id} > GET)

[netmilk]

Hey @JefStat!
Thank you for giving Dredd with Swagger a try and providing this feedback.

Have you tried to use default property for the parameter?

Would you mind sharing with me a snippet of your Swagger document with this problem?

[JefStat]

I've not tried default since the path value is required.

Here's the path.

"/events/{id}": {
            "get": {
                "tags": ["Events"],
                "operationId": "EventsByIdGet",
                "produces": ["application/json"],
                "parameters": [{
                    "name": "id",
                    "in": "path",
                    "required": true,
                    "type": "string"
                }, {
                    "name": "Authorization",
                    "in": "header",
                    "description": "access token",
                    "required": true,
                    "type": "string"
                }],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/Event"
                        }
                    }
                },
                "deprecated": false
            }
        },

[honzajavorek]

@JefStat This is Swagger format's limitation. You are correct that Swagger doesn't allow specifying example values for parameters which aren't "in": "body".

What Dredd currently supports is to specify the value by:

• default - That obviously doesn't make sense when the parameter is required.
• enum - Dredd chooses the first provided enum value.

Neither one of those ways is very convenient if you want to describe just sample value. One way could be to use hooks to inject values, the other way would be to enhance the Swagger format - either by proposing sample values as part of the standard or introducing something like x-example.

[honzajavorek]

This example can provide an idea on how the hooks working around the issue could look like.

[netmilk]

@honzajavorek I think fallback to default value would be reasonable with some warning even though it doesn't' really make sense to provide defaults for required parameters. #555

[kostadinstoilov]

@honzajavorek How would the example you gave work? Dredd emits a compilation error when it doesn't have an example value. As far as I understand it won't go pass the parse phase.

[honzajavorek]

@kostadinstoilov You are right, that won't work as I thought 😐

[kostadinstoilov]

Personally, what I would find most useful in this scenario is to have support for a hook which injects example path values before parsing, compiling and so on. The most common use case for path variables I can think of is resource identifiers, which are not deterministic and could be environment specific so providing a hook seems the best solution to me.

[hskrasek]

Should default be working? Because that doesn't seem to be the case in v1.2.0. Example of a path I've written in Swagger:

"/waterfalls/{placement}": {
      "get": {
        "tags": [
          "Waterfalls"
        ],
        "summary": "Get a waterfall",
        "description": "Get a waterfall based on the placement within the application",
        "operationId": "getWaterfall",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "name": "Device-Info",
            "in": "header",
            "type": "string",
            "description": "A key/value pair header containing data about the application and the device",
            "required": true
          }
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "An ad waterfall",
            "schema": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                },
                "data": {
                  "type": "object",
                  "properties": {
                    "waterfall": {
                      "$ref": "#/definitions/Waterfall"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Waterfalls"
        ],
        "summary": "Delete a waterfall",
        "description": "Delete a waterfall by placement",
        "operationId": "deleteWaterfall",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "parameters": [],
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "204": {
            "description": "Successfully deleted a waterfall"
          }
        }
      },
      "parameters": [
        {
          "name": "placement",
          "in": "path",
          "type": "string",
          "description": "Where the AD is being displayed",
          "required": true,
          "default": "684936a4-f1f5-48ed-9378-ca9e31cf76a7"
        }
      ]
    }

[hskrasek]

Ignore my comment, upgraded to 1.4.0 and got past the "ignoring default issue". Agree that specifying a default for a required param isn't ideal though

[honzajavorek]

@hskrasek I'm glad it works! We will introduce x-example soon, that should be definite solution.

[tomas-fp]

@honzajavorek any update about x-example support??. I would like to define a field as x-test-value in order to define a custom test value used by dredd. The problem is that currently language hooks are not triggered if no default or enum values are present, failing before reaching that phase.

Any solution or workaround around this?

[honzajavorek]

@tomas-fp x-example is already implemented. See docs. This issue should have been closed already (https://github.com/apiaryio/dredd/issues/555 and https://github.com/apiaryio/dredd/issues/561).

[unnativ]

Thank you so much... i got output because of your code. thank you