Comment décrire un modèle de Swagger pour un tableau avec des objets simples?
j'ai un service de repos à documenter, certains d'entre eux acceptent le tableau simple comme:
[
{ "name":"a" },
{ "name":"b" },
{ "name":"c" }
]
Comment puis-je décrire ceci dans la section Modèle Swagger ? Je ne peux créer 'tableau'
model {
properties: { "arr": { "type":"array", ......
mais il décrit les données comme ceci:
"arr": [
{ "name":"a" },
{ "name":"b" },
{ "name":"c" }
]
7 réponses
Tony YUEN était proche, mais pas de cigare. C'est la bonne définition en utilisant YAML dans 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
cela produit:
stackoverflow2[
{
name: string
}
]
L'exemple de Tony produit:
[
stackoverflow {
name: string
}
]
Complet Swagger/OpenAPI en YAML (copier-coller)
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
Voici une version JSON de 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"
}
}
}
}
}
Il ressemble probablement à ceci:
...
"parameters" : [{
"name" : "whatEverThatArrayCalled",
"type" : "array",
"items" : {
"$ref" : "whatEverThatArrayCalled"
}
...
}],
"models" : {
{
"id" : "whatEverThatArrayCalled",
"properties":
{
"whatEverThatArrayCalled" :
{
"type" : "array",
"items":{"name":"a",
"name":"b",
"name":"c"
},
}
}
}
}
...
Coller http://editor.swagger.io/#/ et cliquez sur "essayez cette opération"
{
"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"
}
}
}
}
}
}
j'ai essayé la suivante dans l'éditeur.swagger.io, il répond à la demande de cette question et de travaux. Le corps de requête POST attend un tableau. Le tableau est composé d'éléments' stackoverflow'. Chaque élément est un objet, qui a une propriété de nom.
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/stackoverflow'
responses:
200:
description: OK
definitions:
stackoverflow:
type: object
properties:
name:
type: string
description: name of the object
parameters:
- name: "items"
in: "formData"
description: "description"
required: "true"
type: "array"
items:
type: "object"
additionalProperties:
properties:
name:
type: "string"
selon leur docs https://swagger.io/docs/specification/data-models/dictionaries/, cela devrait aboutir à un tableau avec des objets qui ont une propriété appelée name et datatype est string.
On peut y accéder sur le corps des requêtes, quelque chose comme request.body.items
mise à Jour:
il me semble qu'il est assez à faire (sans le additionalproperties):
items:
type: object
properties:
name:
type: string
Maintenant vous avez les articles où chaque a une clé appelée nom et une valeur correspondante.
si c'est ça, ce que le TO demandait....
tenir compte du format de la matrice que vous avez mentionnés
[
{ "name":"a" },
{ "name":"b" },
{ "name":"c" }
]
je suppose que le format suivant peut être utilisé:
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
si ma compréhension est correcte, je pense que ce qui suit peut ce que vous voulez.
Comme vous l'avez mentionné,
certains d'entre eux acceptent simple array
Ensuite, il serait passé à travers un paramètre.
"parameters" : [{
"name" : "param_name",
"type" : "array",
"items" : {
"$ref" : "M"
}
...
}]
...
"models" : {
"M": {
"id" : "M",
"properties": {
"name" : {
"type" : "string"
}
}
}