Swagger/OpenAPI - 認可レベルに応じた多様なモデル表現

Question

認可レベルに応じてモデルごとに異なる表現がある場合、どのようにSwaggerモデルを使用しますか。例えば

は、管理者のための国のモデルは次のようになります。

definitions: 
    Country: 
    type: object 
    properties: 
     id: 
     type: integer 
     format: int64 
     name: 
     type: string 
     example: The Netherlands 
     code: 
     type: string 
     example: NL 
     created_at: 
     type: string 
     example: 2017-06-01 13:37:00 
     updated_at: 
     type: string 
     example: 2017-06-01 14:00:00 

しかし、普通のユーザーモデルは私がモデル定義を配置するために検討していたこの

definitions: 
    Country: 
    type: object 
    properties: 
     id: 
     type: integer 
     format: int64 
     name: 
     type: string 
     example: The Netherlands 
     code: 
     type: string 
     example: NL 

のように見えます

/admin/countries/{countryId}: 
    get: 
     tags: 
     - AdminCountries 
     summary: Find a country by ID 
     operationId: adminCountriesGetById 
     security: 
     - Bearer: [] 
     parameters: 
     - in: path 
      type: integer 
      format: int64 
      name: countryId 
      required: true 
     responses: 
     '200': 
      description: Success 
      schema: 
      type: object 
      properties: 
       id: 
       type: integer 
       format: int64 
       name: 
       type: string 
       example: The Netherlands 
       code: 
       type: string 
       example: NL 
       created_at: 
       type: string 
       example: 2017-06-01 13:37:00 
       updated_at: 
       type: string 
       example: 2017-06-01 14:00:00 

私の "解決策"がcorrecであるかどうかはわかりませんこれを処理する方法。

Answer 1

今後のOpenAPI仕様3.0では、複数の要求/応答本体を定義するためにoneOfがサポートされる予定です。

2.0では、管理者固有のプロパティをオプションとして定義し、descriptionを使用して、これらのプロパティが管理者用のものであり、通常のユーザー用ではないことを文書化することができます。