swaggerで再利用可能な配列定義を作成

Question

私はSwagger 2.0を使用してAPIの定義/ドキュメントファースト仕様を作成しています。私は、ほとんどの再利用可能なコンポーネントを定義セクションに分割しましたが、定数の配列に対する再利用可能な定義を作成する方法を理解するのに問題があります。

例えば、私はこの1つのように、画像を返しますいくつかのパスを持っている：

paths: 
    /resource/{imageId}: 
    get: 
     produces: 
     - image/jpeg 
     - image/png 
     - image/gif 
     parameters: 
     - in: path 
      name: imageId 
      type: string 
      required: true 
     responses: 
     200: 
      description: Success 
      schema: 
      type: file 

をうまく動作しますが、私はの値の再利用可能な配列を定義できるようにしたいと思います要素を「生成」するので、画像を生成するすべてのパスに対して同じリストを再利用できます。

以下は、直感的なアプローチのように思えますが、闊歩はimageMimeTypesの定義が無効であることを報告します。

paths: 
    /resource/{imageId}: 
    get: 
     produces: 
     $ref: "#/definitions/imageMimeTypes" 
     parameters: 
     - in: path 
      name: imageId 
      type: string 
      required: true 
     responses: 
     200: 
      description: Success 
      schema: 
      type: file 
definitions: 
    imageMimeTypes: 
    - image/jpeg 
    - image/png 
    - image/gif 

それは、このような配列のための定義を作成することは可能ですか？もしそうなら、どんな構文を使うべきですか？

Answer 1

まず、producesの値がの操作で使用されている場合は、それらをグローバルproducesとして定義し、必要に応じて上書きすることができます。

produces: 
    - image/jpeg 
    - image/png 
    - image/gif 

paths: 
    /resource/{imageId}: 
    get: 
     # Inherits global "produces" 
     ... 
    /something: 
    get: 
     # Overrides global "produces" 
     produces: 
     - application/json 
     ... 

producesが$ref値を持つことができないので、あなたの第二の例では、有効ではありません。しかし、YAMLアンカーを使って同様の効果を得ることができます。アンカーは、使用する前に定義する必要があるため、パス定義の上にリストを置く必要があります。

x-types: 
    imageMimeTypes: &IMAGE-MIME-TYPES 
    - image/jpeg 
    - image/png 
    - image/gif 

paths: 
    /resource/{imageId}: 
    get: 
     produces: *IMAGE-MIME-TYPES 
     parameters: 
     - in: path 
      name: imageId 
      type: string 
      required: true 
     responses: 
     200: 
      description: Success 
      schema: 
      type: file 

は、私は、キーx-types代わりdefinitions 1）definitionsための拡張の下のリストを入れて、入力と出力のモデルではなく、ランダムなリストのために意図され、そして2）闊歩エディタで「未使用の定義」という警告を防ぐために。

これは、少なくともSwagger EditorとSwagger UIで動作します。