openapi: 3.0.0
info:
  title: Link Example
  version: 1.0.0
paths:
  /2.0/users/{username}:
    get:
      operationId: getUserByName
      parameters:
      - name: username
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The User
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/user'
          links:
            userRepositories:
              $ref: '#/components/links/UserRepositories'
  /2.0/repositories/{username}:
    get:
      operationId: getRepositoriesByOwner
      parameters:
        - name: username
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: repositories owned by the supplied user
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/repository'
          links:
            userRepository:
              $ref: '#/components/links/UserRepository'
  /2.0/repositories/{username}/{slug}:
    get:
      operationId: getRepository
      parameters:
        - name: username
          in: path
          required: true
          schema:
            type: string
        - name: slug
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The repository
          content:
              application/json:
                schema:
                  $ref: '#/components/schemas/repository'
          links:
            repositoryPullRequests:
              $ref: '#/components/links/RepositoryPullRequests'
  /2.0/repositories/{username}/{slug}/pullrequests:
    get:
      operationId: getPullRequestsByRepository
      parameters:
      - name: username
        in: path
        required: true
        schema:
          type: string
      - name: slug
        in: path
        required: true
        schema:
          type: string
      - name: state
        in: query
        schema:
          type: string
          enum:
            - open
            - merged
            - declined
      responses:
        '200':
          description: an array of pull request objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/pullrequest'
  /2.0/repositories/{username}/{slug}/pullrequests/{pid}:
    get:
      operationId: getPullRequestsById
      parameters:
      - name: username
        in: path
        required: true
        schema:
          type: string
      - name: slug
        in: path
        required: true
        schema:
          type: string
      - name: pid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: a pull request object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pullrequest'
          links:
            pullRequestMerge:
              $ref: '#/components/links/PullRequestMerge'
  /2.0/repositories/{username}/{slug}/pullrequests/{pid}/merge:
    post:
      operationId: mergePullRequest
      parameters:
      - name: username
        in: path
        required: true
        schema:
          type: string
      - name: slug
        in: path
        required: true
        schema:
          type: string
      - name: pid
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: the PR was successfully merged
components:
  links:
    UserRepositories:
      # returns array of '#/components/schemas/repository'
      operationId: getRepositoriesByOwner
      parameters:
        username: $response.body#/username
    UserRepository:
      # returns '#/components/schemas/repository'
      operationId: getRepository
      parameters:
        username: $response.body#/owner/username
        slug: $response.body#/slug
    RepositoryPullRequests:
      # returns '#/components/schemas/pullrequest'
      operationId: getPullRequestsByRepository
      parameters:
          username: $response.body#/owner/username
          slug: $response.body#/slug
    PullRequestMerge:
      # executes /2.0/repositories/{username}/{slug}/pullrequests/{pid}/merge
      operationId: mergePullRequest
      parameters:
        username: $response.body#/author/username
        slug: $response.body#/repository/slug
        pid: $response.body#/id
  schemas:
    user:
      type: object
      properties:
        username:
          type: string
        uuid:
          type: string
    repository:
      type: object
      properties:
        slug:
          type: string
        owner:
          $ref: '#/components/schemas/user'
    pullrequest:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
        repository:
          $ref: '#/components/schemas/repository'
        author:
          $ref: '#/components/schemas/user'