如何定义 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 提供 'default' 值来为所有输入字段(包括正文输入参数)填充 Swagger UI。我的 body 参数是一个引用对象,如下所示。我如何定义返回的 swagger JSON 以在单击 "Try this operation" 时自动填充请求的正文部分?
下面是 Swagger UI 中未填充 default/example 数据的示例 Swagger 规范。
{
"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"
]
}
}
}
我一直在通过单击 File->Paste JSON...
在 http://editor.swagger.io/#/ 测试此 json。然后我单击 "Try this operation"
,向下滚动并观察我的 body 参数的值未填充 - 这就是我想要更改的内容。
提前感谢您的任何建议。
要获得示例值,您只需在需要的地方添加 "example" 属性:
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
不幸的是,在线编辑器没有提供它们,但 SwaggerUI 提供了:
要填充单击 "Try this operation" 时要使用的默认值,您只需为定义中的属性添加 'default' 参数。这适用于在线编辑器:
{
"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",
"default": "The default Action"
},
"applyToBase":{
"type":"string",
"description":"A boolean value that defines the behaviour of the request against the base",
"default": "0"
},
"addOnIDs":{
"type":"string",
"description":"The identifiers for the add-ons",
"default": "The default Add-On"
}
},
"required":[
"action",
"applyToBase",
"addOnIDs"
]
}
}
}
```
我们当前的部署模式要求我手动编写我的 swagger json 输出,这些输出将由我公司使用的基于 Swagger 的 UI 使用。我希望我正在写的 json 提供 'default' 值来为所有输入字段(包括正文输入参数)填充 Swagger UI。我的 body 参数是一个引用对象,如下所示。我如何定义返回的 swagger JSON 以在单击 "Try this operation" 时自动填充请求的正文部分?
下面是 Swagger UI 中未填充 default/example 数据的示例 Swagger 规范。
{
"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"
]
}
}
}
我一直在通过单击 File->Paste JSON...
在 http://editor.swagger.io/#/ 测试此 json。然后我单击 "Try this operation"
,向下滚动并观察我的 body 参数的值未填充 - 这就是我想要更改的内容。
提前感谢您的任何建议。
要获得示例值,您只需在需要的地方添加 "example" 属性:
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
不幸的是,在线编辑器没有提供它们,但 SwaggerUI 提供了:
要填充单击 "Try this operation" 时要使用的默认值,您只需为定义中的属性添加 'default' 参数。这适用于在线编辑器:
{
"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",
"default": "The default Action"
},
"applyToBase":{
"type":"string",
"description":"A boolean value that defines the behaviour of the request against the base",
"default": "0"
},
"addOnIDs":{
"type":"string",
"description":"The identifiers for the add-ons",
"default": "The default Add-On"
}
},
"required":[
"action",
"applyToBase",
"addOnIDs"
]
}
}
}
```