如何定义 Swagger 2.0 JSON 以填充 Swagger UI 中的默认正文参数对象? [英] How to define Swagger 2.0 JSON to populate default body parameter object in Swagger UI?
问题描述
我们当前的部署模式要求我手动编写我的 swagger json 输出，这些输出将由我公司使用的基于 Swagger 的 UI 使用.我希望我正在编写的 json 提供默认"值来填充所有输入字段的 Swagger UI，包括 body 输入参数.我的 body 参数是一个引用对象，如下所示.我如何定义返回的 swagger JSON 以在单击尝试此操作"时自动填充请求的正文部分?
在 Swagger UI 中没有填充默认/示例数据的示例 Swagger 规范如下.
<代码>{"招摇":"2.0",信息":{"description":"示例 API 描述","title":"示例标题",版本":v3.0"},标签":[{名称":v3"}],消耗":[应用程序/json"],产生":[应用程序/json"],路径":{/v3/api/{subscriptionID}/example":{邮政":{标签":[v3"],"description":"这个 API 会做一些事情",消耗":[应用程序/json"],产生":[应用程序/json"],参数":[{"name":"接受","in":"标题","description":"Accept 请求头字段可用于指定响应可接受的媒体类型.如果未提供，默认值为 application/json",必需":假，"默认":"应用程序/json",类型":字符串"},{"name":"内容类型","in":"标题","description":"请求正文的 MIME 类型.对于 PUT、POST 和 PATCH 是必需的，其中需要提供请求正文.",必需":真，"default":"application/json; charset=utf-8",类型":字符串"},{"name":"company_locale","in":"标题","description":"此特定交易的客户在特定区域偏好中所说的所需语言.由两种小写语言组成",必需":真，"default":"en_US",类型":字符串"},{"name":"originatingip","in":"标题","description":"调用设备或浏览器的原始 IP 地址.",必需":真，"默认":"100.100.10.1",类型":字符串"},{"name":"transaction_id","in":"标题","description":"此服务调用的事务标识符.",必需":真，"默认":"1e2bd51d-a865-4d37-9ac9-c345dc59119b",类型":字符串"},{"name":"订阅号","in":"路径","description":"代表已订阅产品组合的唯一标识符.",必需":真，"默认":"1e2bd51d",类型":字符串"},{"name":"body","in":"身体","description":"请求正文",必需":真，架构":{"$ref":"#/definitions/exampleDefinition"}}],回复":{200":{"描述":"好的",标题":{交易ID":{"类型":"字符串","默认":"de305d54-75b4-431b-adb2-eb6b9e546013","description":"服务事务尝试的标识符."}}}}}}},定义":{示例定义":{"类型":"对象","description":"请求示例定义的详细信息",特性":{行动":{"类型":"字符串","description":"指定要采取的行动"},应用到基础":{"类型":"字符串","description":"一个布尔值，用于定义请求对基的行为"},addOnIDs":{"类型":"字符串","description":"附加组件的标识符"}},必需的":[行动"，"applyToBase",附加ID"]}}}我一直在
Our current deployment patterns require me to manually write my swagger json output that will be consumed by the Swagger-based UI in use at my company. I'd like the json I'm writing to provide 'default' values to populate the Swagger UI for all input fields, including the body input parameter. My body parameter is a referenced object as seen below. How do I define the returned swagger JSON to auto populate the body portion of the request when the "Try this operation" is clicked?
An example Swagger spec that has no default/example data populated in the Swagger UI is below.
{
"swagger":"2.0",
"info":{
"description":"Example API Description",
"title":"Example Title",
"version":"v3.0"
},
"tags":[
{
"name":"v3"
}
],
"consumes":[
"application/json"
],
"produces":[
"application/json"
],
"paths":{
"/v3/api/{subscriptionID}/example":{
"post":{
"tags":[
"v3"
],
"description":"This API will do something",
"consumes":[
"application/json"
],
"produces":[
"application/json"
],
"parameters":[
{
"name":"Accept",
"in":"header",
"description":"The Accept request-header field can be used to specify the media types which are acceptable for the response. If not provided, the default value will be application/json",
"required":false,
"default":"application/json",
"type":"string"
},
{
"name":"Content-Type",
"in":"header",
"description":"The MIME type of the body of the request. Required for PUT, POST, and PATCH, where a request body is expected to be provided.",
"required":true,
"default":"application/json; charset=utf-8",
"type":"string"
},
{
"name":"company_locale",
"in":"header",
"description":"The desired language as spoken in a particular region preference of the customer of this particular transaction. Consists of two lower case language",
"required":true,
"default":"en_US",
"type":"string"
},
{
"name":"originatingip",
"in":"header",
"description":"The originating ip address of the calling device or browser.",
"required":true,
"default":"100.100.10.1",
"type":"string"
},
{
"name":"transaction_id",
"in":"header",
"description":"The transaction identifier for this invocation of the service. ",
"required":true,
"default":"1e2bd51d-a865-4d37-9ac9-c345dc59119b",
"type":"string"
},
{
"name":"subscriptionID",
"in":"path",
"description":"The unique identifier that represents the subscribed portfolio of products.",
"required":true,
"default":"1e2bd51d",
"type":"string"
},
{
"name":"body",
"in":"body",
"description":"The body of the request",
"required":true,
"schema":{
"$ref":"#/definitions/exampleDefinition"
}
}
],
"responses":{
"200":{
"description":"OK",
"headers":{
"transaction_id":{
"type":"string",
"default":"de305d54-75b4-431b-adb2-eb6b9e546013",
"description":"The identifier for the service transaction attempt."
}
}
}
}
}
}
},
"definitions":{
"exampleDefinition":{
"type":"object",
"description":"Request details for Example Definition",
"properties":{
"action":{
"type":"string",
"description":"Specifies the action to be taken"
},
"applyToBase":{
"type":"string",
"description":"A boolean value that defines the behaviour of the request against the base"
},
"addOnIDs":{
"type":"string",
"description":"The identifiers for the add-ons"
}
},
"required":[
"action",
"applyToBase",
"addOnIDs"
]
}
}
}
I have been testing this json at http://editor.swagger.io/#/ by clicking File->Paste JSON.... I then click "Try this operation", scroll down and observe that the values of my body parameter are not populated - that's what I'd like to change.
Thanks in advance for any suggestions.
To have example values, you just have to add an "example" property where needed:
exampleDefinition:
type: object
description: Request details for Example Definition
properties:
action:
type: string
description: Specifies the action to be taken
example: An action value
applyToBase:
type: string
description: >-
A boolean value that defines the behaviour of the request against the base
example: An apply to base value
addOnIDs:
type: string
description: The identifiers for the add-ons
example: an ID
Unfortunately the online editor don't propose them but SwaggerUI does:
这篇关于如何定义 Swagger 2.0 JSON 以填充 Swagger UI 中的默认正文参数对象?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
