No sample values or examples provided for API Conformance Scan

Issue ID: warning-sample-undefined

Description

One or more schema or parameter objects in your API are missing sample values or examples that Conformance Scan could use to generate successful happy path requests.

When you scan an API, Conformance Scan generates and sends a happy path request to all operations in your API to establish a successful benchmark against which it can then compare the results from the intentionally malformed test requests. Any operations where the happy path request fails are skipped in the scan.

To successfully call the API operations, Conformance Scan must follow the OpenAPI definition of the API and provide all required parameters in the calls. It may be very difficult to create valid values for some things, like some object schemas, or strings with a very specific pattern. To ensure best performance, we recommend including samples or examples directly in your OpenAPI definition by using the x-42c-sample or example objects.

For more details, see:

Example

The following is an example of how this issue could look in your API definition. The property name is quite well defined, but it does not provide one or more sample values that Conformance Scan could use:

{
    "definitions": {
        "Dog": {
            "type": "object",
            "additionalProperties": false,
            "required": [
                "name"
            ],
            "properties": {
                "name": {
                    "type": "string",
                    "maxLength": 20,
                    "pattern": "^[A-Za-z]{3,20}$"
                }     
                // ...
            }
        }
    }
}

Remediation

Make sure that you define sample values using the properties x-42c-sample or example for schema objects:

{
    "definitions": {
        "Dog": {
            "type": "object",
            "additionalProperties": false,
            "required": [
                "name"
            ],
            "properties": {
                "name": {
                    "type": "string",
                    "maxLength": 20,
                    "pattern": "^[A-Za-z]{3,20}$",
                    "x-42c-sample": "Porkchop"
                }     
                // ...
            }
        }
    }
}

If you need to define an array of sample values, use the property examples:

{
    "definitions": {
        "Dog": {
            "type": "object",
            "additionalProperties": false,
            "required": [
                "name"
            ],
            "properties": {
                "name": {
                    "type": "string",
                    "maxLength": 20,
                    "pattern": "^[A-Za-z]{3,20}$"
                }     
                // ...
            },
            "examples": [
                "Porkchop",
                "Jimmy Chew",
                "Bark Twain"
            ]
        }
    }
}

For parameter objects in body, you can use the property x-42c-sample or reference a subschema that has a sample defined (in this case, you do not have to define another sample in the parameter itself).

For simple parameter objects, you can only use the property x-42c-sample:

{
    "parameters": [
        {
            "name": "limit",
            "in": "query",
            "description": "How many items to return at one time (max 100)",
            "required": false,
            "type": "integer",
            "format": "int32",
            "x-42c-sample":0
        }
    ]
}