オープンAPIのオブジェクトIDに対して$ refを使用する必要があります

Question

SwaggerでOpenAPIのスキーマを作成していますが、$ref要素を悪用しているかどうかはわかりません。私は$ref要素は、具体的にどのようにとのオープンAPIの仕様のドキュメントではあまり見ない

User: 
     type: object 
     properties: 
     id: 
      type: string 
      format: uuid 
     name: 
      type: string 
     ... 
Project: 
     type: object 
     properties: 
     id: 
      type: string 
     user_id: 
      $ref: "#/components/schemas/User" 
     ... 

のようなものに似てUserモデルとProjectモデルを、持っていますが、JSONスキーマドキュメント-の中これはオープンAPIは$ref要素は - 私を拡張項目の以下の記述を見つけました：

$ REFを記述するための最も簡単な方法は、それが論理的にそれが指しているものと置き換えてしまうことです。

上記の場合、プロジェクトを投稿したユーザーを参照するだけです。プロジェクトモデルにユーザーに関するすべての情報を含める必要はないと思われます。 user_idのuuidの要素をstringにするほうがよいでしょうか？それとも正しいですか？その場合はuser_idではなく、フィールド名をuserとするのが一般的ですか？

編集： 再帰的な参照がある場合は、私に迷惑をかけていたことの心がわかります。ユーザーが$refのProjectsへの配列を持ち、Projectにもユーザーに$refの配列がある場合、置き換え（それが行われている場合）によって、各モデルが無限に他のものに埋め込まれます。 $refがModelへのポインタに過ぎないと仮定すると、これは実際には起こりそうにないと思いますか？

Answer 1

あなたの例では、（それが全体Userオブジェクトではなく、表示されるだけでuserIdであると仮定した場合）、独自のスキーマにuserId定義を抽出するために意味をなさないかもしれないが、何が起こっているのか明確である：

components: 
    schemas: 
    User: 
     type: object 
     properties: 
     id: 
      $ref: '#/components/schemas/userId' 
     name: 
      type: string 
     ... 
    Project: 
     type: object 
     properties: 
     id: 
      type: string 
     user_id: 
      $ref: "#/components/schemas/userId" 
     ... 
    userId: 
     type: string 
     format: uuid 

しかし、指摘されているものが有効なOpenAPIスキーマオブジェクトである限り、直接$ref〜#/components/schemas/User/properties/idを作成することは何もありません。

JSONリファレンスとOpenAPI仕様で循環参照が許可されているため、ポインタの類推は健全なものです。