避け定型

Question

私のAPIは、従来のステータスコードを尊重し、私は「私のAPI定義

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

の回答の一部に私も遭遇した同様の問題は、私ができることである自分が、同じテキストを繰り返して発見しました列挙型のプロパティとパラメータを取り除きます。スワッガーのコードをもっと乾くようにできますか？

Answer 1

はい、あなたのコードははるかに乾燥します：OpenAPI（fka。Swagger）仕様は、応答、パラメータ、列挙型を含む多くのファクタリング方法を提供します。

再利用可能な応答

は、あなたはあなたの例でErrorを定義し、ほぼ同じ方法で再利用可能な応答を定義することができます。

はまず、

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

そしてルートレベルにresponsesに、例えばStandard404ため、定義を応答を追加

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

再利用可能な任意の操作にresponsesに$ref : '#/responses/Standard404' 404のステータスコードとそれを使用しますパラメータ

再利用可能なパラメータrs、それは同じことです。

まず、たとえばIDために、ルートレベルでparametersで定義したパラメータを追加します。

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

はその後$ref: '#/parameters/ID'とパラメータのいずれかのリストにそれを使用します。 Proの先端：パラメータは、操作レベルでもパスレベルで定義することができます。

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

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

再利用可能な列挙型

あなたがする必要があるのは、文字列型（または整数の定義を定義することです列挙型を持つまたは番号）：

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

そして、あなたはこのように何度でもそれを使用します。

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

全例

ここでは、これらの3のユースケースのための完全な例です：この について

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' 

より多くのあなたがこのtutorial（情報開示：私はそれを書いた）を読んでくださいとOpenAPI Specification。