go-swaggerの【swagger generate】でハマった注意点

経緯

業務でgo-swaggerを使用することとなり、Swagger ファイルを分割していくと方針が決まりました。
分割するに当たり Swagger のディレクトリ構成は以下になりました。

├─swagger
│   ├──サブシステム
│   │  └───業務
│   │        └───画面
│   │              ├───paths.yaml(api定義)
│   │              ├───paths.yaml(api定義)
│   │              └───definitions.yaml(models定義)
│   │
│   ├──swagger.yaml

クライアントの画面ごとに api を呼び出すため、上記のようなディレクトリ構成で管理していこうとなりました。
各画面ごとの api 定義と models 定義を swagger.yaml で呼び込みます。

ハマった点

type: arrayを$refで呼び出す
Pet という model を定義し、配列で呼び込もうとした場合

definitions.yaml

Pet:
  type: "object"
  properties:
    id:
      type: "integer"
      format: "int64"
    name:
      type: "string"
      example: "doggie"

pet.yaml

responses:
  200:
    description: "successful operation"
    schema:
      type: "array"
      items:
        $ref: "./definitions.yaml#/Pet"

swagger.yaml

paths:
  /pet:
    $ref: ./sub_system/business/screen/pet.yaml
definitions:
  Pet:
    $ref: "./sub_system/business/screen/definitions.yaml#/Pet"

しかし上記の構成でswagger generate server -t gen -f ./swagger/swagger.yamlを実行すると。。。

$ swagger generate server -t gen -f ./swagger/swagger.yaml
2022/02/05 02:41:15 validating spec /home/ubuntu/go/src/custom-server/swagger/swagger.yaml
2022/02/05 02:41:15 preprocessing spec with option:  minimal flattening
could not resolve schema: open /home/ubuntu/go/src/custom-server/swagger/definitions.yaml: no such file or directory

上記のようなエラーとなり generate に失敗します 🙃
原因はわかりません。。
SwaggerViewer で確認しても問題ないし、Swagger Editor にも記載されている書き方とほぼ同じなのに。。

対応策

array の model を作成してそれを呼び込む

definitions.yaml

+  PetList:
+    type: "array"
+    items:
+      $ref: "#/Pet"
Pet:
  type: "object"
  properties:
    id:
      type: "integer"
      format: "int64"
    name:
      type: "string"
      example: "doggie"

pet.yaml

responses:
  200:
    description: "successful operation"
    schema:
-      type: "array"
-      items:
-        $ref: "./definitions.yaml#/Pet"
+      $ref: "./definitions.yaml#/PetList"

swagger.yaml

paths:
  /pet:
    $ref: ./sub_system/business/screen/pet.yaml
definitions:
  Pet:
    $ref: "./sub_system/business/screen/definitions.yaml#/Pet"
  PetList:
+    $ref: "./sub_system/business/screen/definitions.yaml#/PetList"

上記だと generate に成功します 👏

課題

分割しているとswagger generateできてもswagger validateで WARNING が出現する 😇

$ swagger validate ./swagger/swagger.yaml
2022/02/05 03:02:41
The swagger spec at "./swagger/swagger.yaml" is valid against swagger specification 2.0
2022/02/05 03:02:41
The swagger spec at "./swagger/swagger.yaml" showed up some valid but possibly unwanted constructs.
2022/02/05 03:02:41 See warnings below:
2022/02/05 03:02:41 - WARNING: definition "#/definitions/PetList" is not used anywhere
2022/02/05 03:02:41 - WARNING: definition "#/definitions/Pet" is not used anywhere