OpenAPI(swagger): 定義したスキーマの使用時に一部を上書きしたい時の小技

UserNameというスキーマ定義があったとする。

UserName:
  type: string
  description: ユーザー氏名
  example: 山田太郎

このUserNameという定義の使用時に、一部を変更したいと思っても↓の書き方では上書きされない。

properties:
  adminName:
    $ref: "#/components/schemas/UserName"
    description: 管理者氏名
    example: 管理者

この書き方では、decriptionは「ユーザー名」だし、exampleは「山田太郎」のままである。

allOfを使って上書きする

しかし、allOf を使って↓のように書くことで上書きすることができる。

properties:
  adminName:
    allOf:
      - $ref: "#/components/schemas/UserName"
    description: 管理者氏名
    example: 管理者

ちょっと Swagger UI の表記を調整したいな、という時に便利。

同じ書き方でオブジェクトのプロパティを上書きすることもできるが、構造に手を入れるぐらいなら新しく定義を作るべき。