如何在 Swagger 中为具有简单对象的数组描述模型？
Posted
技术标签:
【中文标题】如何在 Swagger 中为具有简单对象的数组描述模型？【英文标题】：How to describe a model in Swagger for an array with simple objects? 【发布时间】：2013-11-04 07:41:11 【问题描述】：我有一个 REST 服务要记录， 其中一些接受简单的数组，例如：
[
"name":"a" ,
"name":"b" ,
"name":"c"
]
如何在 Swagger 模型部分中对此进行描述？我只能像
那样创建“命名数组”model
properties: "arr": "type":"array", ......
但它描述的数据是这样的：
"arr": [
"name":"a" ,
"name":"b" ,
"name":"c"
]
【问题讨论】：
如果你想避免手动输入，你可以试试这个 JSON 到 Swagger 定义转换器：roger13.github.io/SwagDefGen 使用 anyOf 。参考：json-schema.org/understanding-json-schema/reference/… 【参考方案1】：如果我的理解是正确的，我认为以下可能是你想要的。
正如你所说，
其中一些接受简单的数组
然后它会通过一个参数传递。
"parameters" : [
"name" : "param_name",
"type" : "array",
"items" :
"$ref" : "M"
...
]
...
模型部分：
"models" :
"M":
"id" : "M",
"properties":
"name" :
"type" : "string"
【讨论】：
我在问如何描述：[ "name":"a" , "name":"b" , "name":"c" ]【参考方案2】：大概是这样的：
...
"parameters" : [
"name" : "whatEverThatArrayCalled",
"type" : "array",
"items" :
"$ref" : "whatEverThatArrayCalled"
...
],
"models" :
"id" : "whatEverThatArrayCalled",
"properties":
"whatEverThatArrayCalled" :
"type" : "array",
"items":"name":"a",
"name":"b",
"name":"c"
,
...
【讨论】：
【参考方案3】：我尝试了editor.swagger.io中的以下内容，它满足了这个问题的要求并且有效。 POST 请求正文需要一个数组。该数组由“***”项组成。每个项目都是一个对象，具有 name 属性。
paths:
/test:
post:
summary: test 123
description: test 123
parameters:
- name: param1
in: body
required: true
description: test param1
schema:
type: array
items:
$ref: '#/definitions/***'
responses:
200:
description: OK
definitions:
***:
type: object
properties:
name:
type: string
description: name of the object
【讨论】：
这是正确答案。密钥是in: body。根据 Swagger 规范：“由于只能有一个有效负载，因此只能有一个 body 参数。body 参数的名称对参数本身没有影响，仅用于文档目的。”【参考方案4】：
Tony YUEN 很接近，但没有雪茄。这是在 OpenAPI/Swagger 中使用 YAML 的正确定义：
/test:
post:
summary: test 123
description: test 123
parameters:
- name: param1
in: body
required: true
description: test param1
schema:
$ref: '#/definitions/***'
responses:
200:
description: OK
这会产生：
***2[
name: string
]
Tony 的例子产生：
[
***
name: string
]
完整的 Swagger/OpenAPI 为 YAML（复制和粘贴）
swagger: '2.0'
################################################################################
# API Information #
################################################################################
info:
version: "Two-point-Oh!"
title: Simple objects in array test
description: |
Simple objects in array test
################################################################################
# Parameters #
################################################################################
paths:
/test:
post:
summary: Array with named objects
description: Array with named objects
parameters:
- name: param1
in: body
required: true
description: test param1
schema:
type: array
items:
$ref: '#/definitions/***'
responses:
200:
description: OK
/test2:
post:
summary: Array with simpel (nameless) objects
description: Array with simpel (nameless) objects
parameters:
- name: param1
in: body
required: true
description: test param1
schema:
$ref: '#/definitions/***2'
responses:
200:
description: OK
definitions:
***:
type: object
properties:
name:
type: string
description: name of the object
***2:
type: array
items:
type: object
properties:
name:
type: string
description: name of the object
这是 Swagger/OpenAPI 的 JSON 版本
"swagger" : "2.0",
"info" :
"description" : "Simple objects in array test\n",
"version" : "Two-point-Oh!",
"title" : "Simple objects in array test"
,
"paths" :
"/test" :
"post" :
"summary" : "Array with named objects",
"description" : "Array with named objects",
"parameters" : [
"in" : "body",
"name" : "param1",
"description" : "test param1",
"required" : true,
"schema" :
"type" : "array",
"items" :
"$ref" : "#/definitions/***"
],
"responses" :
"200" :
"description" : "OK"
,
"/test2" :
"post" :
"summary" : "Array with simpel (nameless) objects",
"description" : "Array with simpel (nameless) objects",
"parameters" : [
"in" : "body",
"name" : "param1",
"description" : "test param1",
"required" : true,
"schema" :
"$ref" : "#/definitions/***2"
],
"responses" :
"200" :
"description" : "OK"
,
"definitions" :
"***" :
"type" : "object",
"properties" :
"name" :
"type" : "string",
"description" : "name of the object"
,
"***2" :
"type" : "array",
"items" :
"$ref" : "#/definitions/***2_inner"
,
"***2_inner" :
"properties" :
"name" :
"type" : "string",
"description" : "name of the object"
【讨论】：
【参考方案5】：将此粘贴到http://editor.swagger.io/#/ 并点击“尝试此操作”
"swagger": "2.0",
"info":
"version": "1.0.0",
"title": "Privacy-Service API"
,
"paths":
"/allNames":
"post":
"consumes": [
"application/json",
"application/xml"
],
"produces": [
"application/json",
"application/xml"
],
"parameters": [
"name": "request",
"in": "body",
"schema":
"$ref": "#/definitions/ArrayOfNames"
],
"responses":
"200":
"description": "List of names",
"schema":
"type": "array",
"items":
"type": "string"
,
"definitions":
"ArrayOfNames":
"type": "array",
"items":
"minItems": 1,
"type": "object",
"required": [
"name"
],
"properties":
"name":
"type": "string"
【讨论】：
没有application/json这可能吗？
application/json 是默认值。您可以完全删除它，甚至可以添加 xml 作为替代【参考方案6】：
parameters:
- name: "items"
in: "formData"
description: "description"
required: "true"
type: "array"
items:
type: "object"
additionalProperties:
properties:
name:
type: "string"
根据他们的文档https://swagger.io/docs/specification/data-models/dictionaries/，这应该会产生一个数组，其中的对象具有名为 name 的属性并且数据类型是字符串。
可以通过请求正文访问它，例如request.body.items
更新：
看起来就足够了（没有额外的属性）：
items:
type: object
properties:
name:
type: string
现在你得到了每个项目都有一个名为 name 的键和一个对应的值。
如果是这样，TO 要求的是什么......
【讨论】：
感谢您提供此代码 sn-p，它可能会提供一些有限的即时帮助。 proper explanation would greatly improve its long-term value 通过展示为什么这是一个很好的解决问题的方法，并将使其对未来有其他类似问题的读者更有用。请edit您的回答添加一些解释，包括您所做的假设。【参考方案7】：考虑到你提到的数组的格式
[
"name":"a" ,
"name":"b" ,
"name":"c"
]
我猜可以使用以下格式：
paths:
/test:
post:
description: Test request
operationId: test
parameters:
- in: body
name: requestParameter
required: true
schema:
type: array
items:
properties:
name:
type: string
responses:
'200':
description: Success response
【讨论】：
以上是关于如何在 Swagger 中为具有简单对象的数组描述模型？的主要内容，如果未能解决你的问题，请参考以下文章
Swagger 在 ASP.CORE 3 中为字典生成不正确的 URL
如何在 OpenAPI (Swagger) 中为同一路径定义不同的查询参数？
如何在 Lumen/Laravel 中为 REST API 集成 Swagger？
如何使用 Quarkus 在 RestEasy 中为 MultipartFormDataInput 提供 swagger 注释