Allow Links to Schema objects (Primitives/Objects/...)

[ochatelain]

Situation:

• Links to operation could start from data-types rather than from other operations

Example:

Link from Type (UserId)

components:
  schemas:
    UserId:
      type: integer
      format: int64
      example: 10
      # -----------------------------------------------------
      # Links
      # -----------------------------------------------------
      links:
        GetUserByUserId: # <---- arbitrary name for the link
        operationId: getUser
        parameters:
          userId: '/'
        description: >
          Anyx `UserId` field can be used as parameter for
          the `userId` parameter in `GET /users/{userId}`.

Links from Object (User)

      # -----------------------------------------------------
      # Links
      # -----------------------------------------------------
      links:
        GetUserByUserId: # <---- arbitrary name for the link
        operationId: getUser
        parameters:
          userId: '$id'
        description: >
          The `id` value of Users can be used as parameter for
          the `userId` parameter in `GET /users/{userId}`.

components:
  schemas:
    User:
      x-swagger-router-model: io.swagger.petstore.model.User
      properties:
        id:
          type: integer
          format: int64
          example: 10
        username:
          type: string
          example: theUser
        firstName:
          type: string
          example: John
        lastName:
          type: string
          example: James
        email:
          type: string
          example: [email protected]
        password:
          type: string
          example: 12345
        phone:
          type: string
          example: 12345
        userStatus:
          type: integer
          format: int32
          example: 1
          description: User Status
      xml:
        name: user
      type: object
      # -----------------------------------------------------
      # Links
      # -----------------------------------------------------
      links:
        GetUserByUserId: # <---- arbitrary name for the link
        operationId: getUser
        parameters:
          userId: '/id'
        description: >
          The `id` value of Users can be used as parameter for
          the `userId` parameter in `GET /users/{userId}`.

[handrews]

This scale of change is best discussed in Moonwalk (and can be backported if relevant and we decide to keep the 3.x line going). Closing in favor of:

• Improvements for links in v4 sig-moonwalk#58