was bedeutet "Inhalt": Mittelwert in Prahlerei/OpenAPI "Antworten":

Question

Mit Swagger/OpenAPI (und anschließend Prahlerei-codegen) Ich war nicht in der Lage, was die sollte Unterschied finden zwischen

Dies seinen genommen, direclty von https://swagger.io/specification/#responsesObject (erstes Beispiel json Format)

"responses" : { 
    "200": { 
    "description": "a pet to be returned", 
    "content": { 
     "application/json": { 
     "schema": { 
      "$ref": "#/components/schemas/Pet" 
} } } } } 

und

"reponses" : { 
    "200": { 
    "description": "a pet to be returned", 
    "schema": { 
     "$ref": "#/components/schemas/Pet" 
} } } 

Ich habe dieses Beispiel in eine triviale json swagger spec (json) geschrieben und führe den Swagger-Codegen (python, flask) aus, um meine Controller und mein Modell zu generieren. Yaml scheint die bevorzugte interne Repräsentation zu sein. Wenn der Generator läuft, erstellt er eine Yaml-Datei.

Mit dem ehemaligen, die Antworttyp ist „None“

responses: 
    200: 
    description: "a pet to be returned" 

während die letztere Ausbeuten, was ich denke, sollte ich erwartet werden:

responses: 
    200: 
    description: "a pet to be returned" 
    schema: 
     $ref: "#/components/schemas/Pet" 

zB das Schema scheint von weggelassen zu werden die erste Syntax mit Content

Was bedeutet Inhalt? Was fehlt mir in dem Beispiel, warum die Content zu einem Nicht-None-Rückgabetyp und einem entsprechenden Schema führt.

Hinweis auf die SwaggerCodgen: der generierte Code entspricht genau das, was die erzeugte yaml sagt, daher habe ich keine dieser Details hier enthalten

Answer 1

Das erste Beispiel ist OpenAPI 3.0 ist das zweite Beispiel OpenAPI 2.0, daher der Unterschied.

Das in OpenAPI 3.0 verwendete Schlüsselwort content ist ein Ersatz für consumes/produces von OpenAPI 2.0. Im Kontext von responses bedeutet content, dass die Antwort einen Textkörper hat und den Medientyp (JSON/XML/etc.) Und die Struktur des Antworttextkörpers angibt.

OpenAPI Version 2.0:

swagger: "2.0" 
... 
paths: 
    /foo: 
    get: 
     produces: 
     - application/json 
     responses: 
     200: 
      description: OK 
      schema: 
      $ref: "#/definitions/Pet" 

OpenAPI 3.0 Version:

openapi: 3.0.0 
... 
paths: 
    /foo: 
    get: 
     responses: 
     "200": 
      description: OK 
      content: 
      application/json: 
       schema: 
       $ref: "#/components/schemas/Pet" 

Die codegen Problem wahrscheinlich durch eine der fololowing verursacht:

• codegen nicht unterstützt OpenAPI 3.0 noch
• die spec ist nicht gültig (zB verwendet ein mi x der Schlüsselwörter 2.0 und 3.0)