Swagger / OpenAPI - Diffrent model representations depending on authorization level - swagger

Question

How do i use the Swagger models when i have diffrent representations for each model depending on the authorization level.
For example, a country model for an administrator looks like this:
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
However, just a regular user model looks like this
definitions:
Country:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
example: The Netherlands
code:
type: string
example: NL
I was considering to place the model definitions in the response like this:
/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
I am not really sure if my "solution" is the correct way to handle this.

Answer 1

The upcoming OpenAPI Specification 3.0 will support oneOf to define multiple possible request/response bodies.
In 2.0, the most you can do is to define the administrator-specific properties as optional and use description to document that these properties are returned for administrators ony and not for regular users.