athlete-api.yaml

openapi: 3.0.0
info:
  title: Athletes API
  version: '0.1-oas3'
servers: []
paths:
  /test-api/v1/athletes:
    get:
      summary: Search for athletes
      parameters: 
      - schema:
          type: string
          maxLength: 20
        name: name-filter
        in: query
        required: true
        examples:
          RESULTS:
            value: Mo
          NO_RESULTS:
            value: ZZZZ
          TOO_LONG:
            value: zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
      responses:
        '200':
          description: Athletes found
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Athlete'
              examples:
                ATHLETES_FOUND:
                  value:
                  - id: 456
                    name: Mo Farah
                    age: 31
                    activities:
                    - name: Running
                      distances:
                      - unit: meters
                        quantity: 5000
                  - id: 565
                    name: Monica Aksamit
                    age: 29
                    activities:
                    - name: Fencing
                      events:
                      - name: Sabre
                      - name: Epée
                ATHLETES_NOT_FOUND:
                  value:
                    []
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400-Error'
              example:
                value:
                  error-code: 400
                  validation-message: 'Query parameter ''name-filter'' is too long. Maximum 20 characters allowed.'
    post:
      summary: Create an athlete
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Athlete'
            examples:
              CREATE_ATHLETE_1:
                value:
                  name: Kelly Holmes
                  activities:
                  - name: Running
                    distances:
                    - unit: meters
                      quantity: 400
                    - unit: meters
                      quantity: 800
                    - unit: meters
                      quantity: 1500
                  - name: Throwing
                    events:
                    - name: javelin
              CREATE_ATHLETE_2:
                value:
                  name: Miles Chamley-Watson
                  age: 23
                  activities:
                  - name: Fencing
                    events:
                    - name: Foil
                    - name: Epée
              INVALID_ATHLETE_DATA:
                value:
                  name: Bobby No-activities
      responses:
        '201':
          description: Athlete Created Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Athlete'
              examples:
                CREATE_ATHLETE_1:
                  value:
                    id: 1
                    name: Kelly Holmes
                    activities:
                    - name: Running
                      distances:
                      - unit: meters
                        quantity: 400
                      - unit: meters
                        quantity: 800
                      - unit: meters
                        quantity: 1500
                    - name: Throwing
                      events:
                      - name: javelin
                CREATE_ATHLETE_2:
                  value:
                    id: 2
                    name: Miles Chamley-Watson
                    age: 23
                    activities:
                    - name: Fencing
                      events:
                      - name: Foil
                      - name: Epée
        '400':
          description: Invalid athlete data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400-Error'
              example:
                value:
                  error-code: 400
                  validation-message: 'Could not create athlete. Athlete must have at least one activity'
  # /test-api/v1/athletes/{id}:
    # parameters:
      # - schema:
          # type: number
        # name: id
        # in: path
        # required: true
        # examples:
          # ATHLETE_ID_1:
            # value: 1
          # ATHLETE_ID_NOT_FOUND:
            # value: -56
    # get:
      # summary: Fetch athlete details
      # tags: []
      # responses:
        # '200':
          # description: Details for the athlete with matching id
          # content:
            # application/json:
              # schema:
                # $ref: '#/components/schemas/Athlete'
              # example:
                # id: 1
                # name: Kelly Holmes
                # activities:
                # - name: Running
                  # distances:
                  # - unit: meters
                    # quantity: 400
                  # - unit: meters
                    # quantity: 800
                  # - unit: meters
                    # quantity: 1500
                # - name: Throwing
                  # events:
                  # - name: javelin
        # '404':
          # description: Athlete with given id not found
    # put:
      # summary: Update athlete details
      # requestBody:
        # content:
          # application/json:
            # schema:
              # $ref: '#/components/schemas/Athlete'
            # examples:
              # UPDATE_ATHLETE_EVENTS:
                # value:
                  # name: Kelly Holmes
                  # activities:
                  # - name: Running
                    # distances:
                    # - unit: meters
                      # quantity: 800
                    # - unit: meters
                      # quantity: 1500
                  # - name: Throwing
                    # events:
                    # - name: wellies
              # UPDATE_ATHLETE_WITH_INVALID_DATA:
                # value:
                  # name: Kelly Holmes
                  # activities:
                  # - name: Hopping
                    # distances:
                    # - unit: miles
                      # quantity: 10
      # responses:
        # '200':
          # description: Updated athlete details
          # content:
            # application/json:
              # schema:
                # $ref: '#/components/schemas/Athlete'
              # example:
                # id: 1
                # name: Kelly Holmes
                # activities:
                # - name: Running
                  # distances:
                  # - unit: meters
                    # quantity: 800
                  # - unit: meters
                    # quantity: 1500
                # - name: Throwing
                  # events:
                  # - name: wellies
        # '400':
          # description: Invalid athlete data
          # content:
            # application/json:
              # schema:
                # $ref: '#/components/schemas/400-Error'
              # example:
                # value:
                  # error-code: 400
                  # validation-message: 'Could not update athlete with ID 1. ''Hopping'' for 10 miles is not a valid activity'
        # '404':
          # description: Athlete with given id not found
components:
  schemas:
    Athlete:
      type: object
      required:
      - name
      - activities
      additionalProperties: false
      properties:
        id:
          type: integer
        name:
          type: string
          maxLength: 50
        age:
          type: integer
        activities:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/Activity'
    Activity:
      type: object
      required:
      - name
      - events
      additionalProperties: false
      properties:
        name:
          type: string
          enum: ['Running', 'Throwing', 'Fencing']
        events:
          type: object 
          oneOf:
          - type: object
            properties:
              events:
                $ref: '#/components/schemas/Events'
            required:
            - events
          - type: object
            properties:
              distances:
                $ref: '#/components/schemas/Distances'
            required:
            - distances
    Events:
      type: array
      minItems: 1
      items:
        $ref: '#/components/schemas/Event'
    Event:
      type: object
      properties:
        name:
          type: string
      required:
      - name
      additionalProperties: false
    Distances:
      type: array
      maxItems: 4
      items:
        $ref: '#/components/schemas/Distance'
    Distance:
      type: object
      properties:
        unit:
          type: string
          enum: ['meters', 'kilometers', 'feet', 'miles']
        quantity:
          type: number
      required:
      - unit
      - quantity
      additionalProperties: false
    400-Error:
      type: object
      properties:
        error-code: 
          type: integer
          maxLength: 3
        validation-message: 
          type: string
      required:
      - validation-message
      additionalProperties: false