How to add examples for path parameters in OpenAPI 3.0

Question

For one of the API Proxy in Azure APIM, we would like to add samples, so that Developers can login to Developer Portal and quickly test it with the samples presented to them, this is possible for Query Parameters and Body, but so for I didn't a way to do it for path parameters.That's why if we add a sample value for it in Azure APIM Portal, it becomes non editable (non deletable as well) field in Azure APIM Developer Portal.

APIM Portal Snapshot APIM Developer Portal Snapshot

{
    "openapi": "3.0.1",
    "info": {
        "title": "Create Account",
        "description": "Create Account for a Customer.",
        "version": "1.0"
    },
    "paths": {
        "/{customerId}": {
            "post": {
                "tags": ["createaccount"],
                "summary": "",
                "description": "",
                "operationId": "createAccount",
                "parameters": [{
                    "name": "employerId",
                    "in": "path",
                    "description": "ID of customer",
                    "required": true,
                    "schema": {
                        "maxLength": 9,
                        "minLength": 1,
                        "enum": ["118"],
                        "type": "string",
                        "default": "118"
                    }
                }],

I tried finding examples in this section, but it skips the Path Parameter part: https://swagger.io/docs/specification/adding-examples/

score 0 · Accepted Answer · answered Aug 04 '23 at 12:48

path parameter becomes non editable

If you want to make the path parameter editable then do the following

"schema": {
"maxLength": 9,
"minLength": 1,
"enum": [""],
"type": "string"
}

Keep enum": [""] as blank and don't provide any default value as "default": "118"

path parameter becomes non removable

You can't remove a path parameter, as path parameters are required property which are entered during operation creation.

"/{customerId}": {
"post": {
"summary": "createAccount",
"description": "createAccount",
"operationId": "createaccount",
"parameters": [{
"name": "customerId",
"in": "path",
"required": true,
"schema": {
"maxLength": 9,
"minLength": 1,
"enum": [""],
"type": "string"
}
}]

If you will try to make required: true as false then it will throw an error

enter image description here

You can set required: true as false in the case of query parameter.

How to add examples for path parameters in OpenAPI 3.0

1 Answers1