英文:
How to add examples for path parameters in OpenAPI 3.0
问题
对于 Azure APIM 中的一个 API 代理，我们想要添加示例，以便开发人员可以登录到开发者门户并快速使用向他们展示的示例进行测试，这对于查询参数和正文是可能的，但到目前为止，我没有找到一种方法来为路径参数执行此操作。这就是为什么如果我们在 Azure APIM 门户中添加一个示例值，它将成为 Azure APIM 开发者门户中不可编辑（也不可删除）的字段的原因。
{
"openapi": "3.0.1",
"info": {
"title": "创建账户",
"description": "为客户创建账户。",
"version": "1.0"
},
"paths": {
"/{customerId}": {
"post": {
"tags": ["createaccount"],
"summary": "",
"description": "",
"operationId": "createAccount",
"parameters": [{
"name": "employerId",
"in": "path",
"description": "客户的ID",
"required": true,
"schema": {
"maxLength": 9,
"minLength": 1,
"enum": ["118"],
"type": "string",
"default": "118"
}
}],
我尝试在这个部分找到示例，但它跳过了路径参数部分：
https://swagger.io/docs/specification/adding-examples/
英文:
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/
答案1
得分: 0
路径参数变为不可编辑
如果要使路径参数可编辑，请执行以下操作：
"schema": {
"maxLength": 9,
"minLength": 1,
"enum": [""],
"type": "string"
}
将 enum": [""] 保留为空白，并且不提供任何默认值，如 default": "118"
路径参数变为不可移除
无法移除路径参数，因为路径参数是必需属性，在操作创建过程中输入。
"/{customerId}": {
"post": {
"summary": "createAccount",
"description": "createAccount",
"operationId": "createaccount",
"parameters": [{
"name": "customerId",
"in": "path",
"required": true,
"schema": {
"maxLength": 9,
"minLength": 1,
"enum": [""],
"type": "string"
}
}]
}
}
如果尝试将 required: true 设置为 false，则会引发错误。
在查询参数的情况下，可以将 required: true 设置为 false。
英文:
> 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
You can set required: true as false in the case of query parameter.
通过集体智慧和协作来改善编程学习和解决问题的方式。致力于成为全球开发者共同参与的知识库，让每个人都能够通过互相帮助和分享经验来进步。
评论