如何在 Swagger 中为具有简单对象的数组描述模型? [英] How to describe a model in Swagger for an array with simple objects?

问题描述

我有一个 REST 服务要记录，其中一些接受简单的数组，如:

<预><代码>[{名称":a"}，{名称":b"}，{名称":c"}]

我如何在 Swagger 模型部分描述这一点?我只能像

一样创建命名数组"

model {属性:{arr":{类型":数组"，......

但它是这样描述数据的:

"arr": [{名称":a"}，{名称":b"}，{名称":c"}]

解决方案

Tony YUEN 很接近，但没有雪茄.这是在 OpenAPI/Swagger 中使用 YAML 的正确定义:

/test:邮政:总结:测试 123描述:测试 123参数:- 名称:参数 1在:身体要求:真实描述:测试参数1架构:$ref: '#/定义/stackoverflow'回应:200:描述:好的

这会产生:

stackoverflow2[{名称:字符串}]

托尼的例子产生:

<预><代码>[堆栈溢出 {名称:字符串}]

以 YAML 形式完成 Swagger/OpenAPI(复制和粘贴)

 招摇:'2.0'############################################################################# API 信息 #############################################################################信息:版本:两点哦！"标题:数组测试中的简单对象说明: |数组测试中的简单对象#############################################################################                                   参数                                 #############################################################################路径:/测试:邮政:摘要:具有命名对象的数组描述:具有命名对象的数组参数:- 名称:参数 1在:身体要求:真实描述:测试参数1架构:类型:数组项目:$ref: '#/定义/stackoverflow'回应:200:描述:好的/测试2:邮政:摘要:带有 simpel(无名)对象的数组描述:带有 simpel(无名)对象的数组参数:- 名称:参数 1在:身体要求:真实描述:测试参数1架构:$ref: '#/定义/stackoverflow2'回应:200:描述:好的定义:堆栈溢出:类型:对象特性:名称:类型:字符串描述:对象名称堆栈溢出2:类型:数组项目:类型:对象特性:名称:类型:字符串描述:对象名称

这是 Swagger/OpenAPI 的 JSON 版本

<代码> {招摇":2.0"，信息":{"description" : "数组测试中的简单对象\n","version" : "两点哦！","title" : "数组测试中的简单对象"},路径":{/测试" : {邮政" : {"summary" : "带有命名对象的数组","description": "带有命名对象的数组",参数" : [ {"in" : "身体",名称":参数1"，描述":测试参数1"，必需":真的，架构":{类型":数组"，项目" : {"$ref" : "#/definitions/stackoverflow"}}}],回应":{200":{说明":好的"}}}},/测试2":{邮政" : {"summary" : "带有简单(无名)对象的数组",描述":带有简单(无名)对象的数组"，参数" : [ {"in" : "身体",名称":参数1"，描述":测试参数1"，必需":真的，架构":{"$ref" : "#/definitions/stackoverflow2"}}],回应":{200":{说明":好的"}}}}},定义":{堆栈溢出" : {类型":对象"，特性" : {名称" : {类型":字符串"，描述":对象名称"}}},stackoverflow2":{类型":数组"，项目" : {"$ref" : "#/definitions/stackoverflow2_inner"}},stackoverflow2_inner":{特性" : {名称" : {类型":字符串"，描述":对象名称"}}}}}

I have a REST services to document, some of them accepts simple array like:

[
  { "name":"a" },
  { "name":"b" },
  { "name":"c" }
]

How do I describe this in Swagger model section ? I can only create 'named array' like

model {
properties: { "arr": { "type":"array", ......

but it describes data like this:

"arr": [
  { "name":"a" },
  { "name":"b" },
  { "name":"c" }
]

解决方案

Tony YUEN was close, but no cigar. This is the proper definition using YAML in OpenAPI/Swagger:

  /test:
post:
  summary: test 123
  description: test 123
  parameters:
    - name: param1
      in: body
      required: true
      description: test param1
      schema:
          $ref: '#/definitions/stackoverflow'
  responses:
    200:
      description: OK

This produces:

stackoverflow2[
  {
     name: string
  }
]

Tony's example produces:

[
  stackoverflow { 
                 name: string
  }
]

Complete Swagger/OpenAPI as YAML (copy & paste)

    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/stackoverflow'
      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/stackoverflow2'
      responses:
        200:
          description: OK
definitions:
  stackoverflow:
    type: object
    properties:
      name:
        type: string
        description: name of the object
  stackoverflow2:
    type: array
    items:
      type: object
      properties:
        name:
          type: string
          description: name of the object

Here's a JSON-version of Swagger/OpenAPI

    {
  "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/stackoverflow"
            }
          }
        } ],
        "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/stackoverflow2"
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "OK"
          }
        }
      }
    }
  },
  "definitions" : {
    "stackoverflow" : {
      "type" : "object",
      "properties" : {
        "name" : {
          "type" : "string",
          "description" : "name of the object"
        }
      }
    },
    "stackoverflow2" : {
      "type" : "array",
      "items" : {
        "$ref" : "#/definitions/stackoverflow2_inner"
      }
    },
    "stackoverflow2_inner" : {
      "properties" : {
        "name" : {
          "type" : "string",
          "description" : "name of the object"
        }
      }
    }
  }
}

这篇关于如何在 Swagger 中为具有简单对象的数组描述模型?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！