Vermeiden vorformulierten in Swagger 2.0

Question

Meine APIs die üblichen Statuscodes zu respektieren, und ich habe festgestellt, mich den gleichen Text in den Antworten Teil meiner api Definition

404: 
      description: The resource doesn't exist 
      schema: 
      $ref: '#/definitions/Error' 
default: 
      description: An unexpected error has occurred 
      schema: 
      $ref: '#/definitions/Error' 

Ein ähnliches Problem habe ich auch begegnen, ist, dass ich kann‘Wiederholung t enum Eigenschaften und Parameter aus. Kann mein Swagger-Code trockener werden?

Answer 1

Ja, Ihr Code kann viel trockener werden: Die OpenAPI (fka. Swagger) -Spezifikation bietet viele Möglichkeiten, Dinge zu berücksichtigen, einschließlich Antworten, Parameter und Enums.

Wiederverwendbare Antworten

können Sie wiederverwendbare Antwort definieren fast auf die gleiche Weise Error in Ihrem Beispiel definiert.

erste Antwort hinzuzufügen, zum Beispiel Standard404, Definition in responses auf Root-Ebene

responses: 
    Standard404: 
    description: The resource doesn't exist 
    schema: 
     $ref: '#/definitions/Error' 

Dann verwenden sie mit einem $ref : '#/responses/Standard404' für 404-Statuscode in responses auf jedem Betrieb

responses: 
    404: 
    $ref: '#/responses/Standard404' 

Wiederverwendbare Parameter

Für wiederverwendbare Parameter rs, es ist dasselbe.

Zunächst einen Parameter hinzu, zum Beispiel ID, Definition in parameters auf Root-Ebene:

parameters: 
    ID: 
    name: id 
    in: path 
    required: true 
    type: string 

es dann mit einem $ref: '#/parameters/ID' in jeder Liste von Parametern verwenden. Pro Spitze: Parameter können auf Betriebsebene festgelegt werden, sondern auch auf dem Weg Ebene:

/other-resources/{id}: 
    get: 
     parameters: 
     - $ref: '#/parameters/ID' 

/resources/{id}: 
    parameters: 
     - $ref: '#/parameters/ID' 

Wiederverwendbare Aufzählungen

Alles, was Sie tun müssen, ist eine Definition des Typs Zeichenfolge zu definieren (oder integer oder Zahl) mit dem enum:

SomeValueWithEnum: 
    type: string 
    enum: 
     - a value 
     - another value 

und es dann so oft nutzen, wie Sie möchten dies wünschen:

Resource: 
    properties: 
     dummyProperty: 
     $ref: '#/definitions/SomeValueWithEnum' 

Voll Beispiel

Hier ist ein vollständiges Beispiel für diese drei Anwendungsfälle:

swagger: '2.0' 

info: 
    version: 1.0.0 
    title: API 
    description: Reusable things example 

paths: 

    /resources: 
    post: 
     responses: 
     200: 
      description: OK 
     default: 
      $ref: '#/responses/Default' 

    /resources/{id}: 
    parameters: 
     - $ref: '#/parameters/ID' 
    get: 
     responses: 
     200: 
      description: OK 
     404: 
      $ref: '#/responses/Standard404' 
     default: 
      $ref: '#/responses/Default' 
    delete: 
     responses: 
     200: 
      description: OK 
     404: 
      $ref: '#/responses/Standard404' 
     default: 
      $ref: '#/responses/Default' 

    /other-resources/{id}: 
    get: 
     parameters: 
     - $ref: '#/parameters/ID' 
     responses: 
     200: 
      description: OK 
     404: 
      $ref: '#/responses/Standard404' 
     default: 
      $ref: '#/responses/Default' 

definitions: 
    Error: 
    properties: 
     message: 
     type: string 

    SomeValueWithEnum: 
    type: string 
    enum: 
     - a value 
     - another value 

    Resource: 
    properties: 
     dummyProperty: 
     $ref: '#/definitions/SomeValueWithEnum' 

    AnotherResource: 
    properties: 
     anotherDummyProperty: 
     $ref: '#/definitions/SomeValueWithEnum' 

parameters: 
    ID: 
    name: id 
    in: path 
    required: true 
    type: string 

responses: 
    Standard404: 
    description: The resource doesn't exist 
    schema: 
     $ref: '#/definitions/Error' 
    Default: 
    description: An unexpected error has occurred 
    schema: 
     $ref: '#/definitions/Error' 

Mehr über dieses Sie sollten diese tutorial (Offenlegung: Ich schrieb es) gelesen und die OpenAPI Specification.