CODEWITHSUNDEEP
documentationswaggerswagger-2.0
Charles L.
Charles L.

Reputation: 6275

Use different example values for parameters in Swagger 2?

I have an API that uses the same definition in more than 1 place, but I want to include different examples for the different places.

To give some context, I have:

parameters:
- in: body
  description: The user object for the new user
  name: body
  schema:
    "$ref": "#/definitions/User"

Which uses the User object. The User object is also returned when a user signs in, and contains more information than what is used to create the user, for example, the user id.

I have an example on the definition, but is there a way I can have a separate example for the POST /user endpoint body parameter?

Upvotes: 1

Views: 232

Answers (1)

fredw
fredw

Reputation: 1419

I suggest having two different objects for the user: UserCreate which is for creating (and perhaps updating) and UserDetail which is returned by post/put/get with full detail. This allows for different examples as you can see below.

You can have UserDetail inherit all the properties from UserCreate by using the allOf construct. In this example, they share name and email and UserDetail has an additional id and href property:

paths:
  /users:
    post:
      parameters:
      - in: body
        name: body
        schema:
          $ref: '#/definitions/UserCreate'      
      responses:
        201:
          description: The created user
          schema:
            $ref: '#/definitions/UserDetail'
  /users/{id}:
    get:
      parameters:
      - in: path
        name: id
        type: string
        required: true
      responses:
        200:
          description: The user
          schema:
            $ref: '#/definitions/UserDetail'

definitions:
  UserCreate:
    properties:
      name:
        type: string
      email:
        type: string
    example:
    - name: Bob
      email: [email protected]
  UserDetail:
    allOf:
    - $ref: '#/definitions/UserCreate'
    - properties:
        id:
          type: string
        href:
          type: string
      example:
      - id: 123
        href: /users/123
        name: Bob
        email: [email protected]

Upvotes: 1

Related Questions