API specification for a demo project, showing off openApi 3.0

openApi.yaml

openapi: 3.0.1
servers:
  - url: https://macrander-toptal.appspot.com/api
    description: Production server (uses live data)
  - url: http://localhost:3002/api
    description: Sandbox server (uses test data)
info:
  description: Toptal Time Management
  version: "1.0.0"
  title: Toptal Time Management
  contact:
    email: cmacrander@gmail.com
tags:
  - name: authentication
    description: setting passwords and logging in
  - name: users
    description: Managing user accounts
  - name: tasks
    description: Managing time-tracking tasks
paths:
  /users:
    get:
      tags:
        - users
      summary: queries all users
      operationId: userQuery
      x-exegesis-controller: userController
      parameters:
        - in: query
          name: email
          description: email address of user
          required: false
          schema:
            type: string
            format: email
      responses:
        '200':
          description: users matching criteria
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '400':
          description: bad input parameter
        '403':
          description: forbidden
    post:
      tags:
        - users
      summary: registers/creates a new user
      operationId: userPost
      x-exegesis-controller: userController
      responses:
        '200':
          description: created user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '409':
          description: user already exists
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewUser'
        description: User to add
  '/users/{userId}':
    get:
      tags:
        - users
      summary: gets a single user
      operationId: userGet
      x-exegesis-controller: userController
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '403':
          description: not allowed
        '404':
          description: not found
    put:
      tags:
        - users
      summary: update a user
      operationId: userPut
      x-exegesis-controller: userController
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '403':
          description: not allowed
        '404':
          description: not found
    delete:
      tags:
        - users
      summary: delete a user
      operationId: userDelete
      x-exegesis-controller: userController
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: user deleted
        '403':
          description: not allowed
        '404':
          description: not found
  /login:
    post:
      tags:
        - authentication
      description: logs in a user
      operationId: login
      x-exegesis-controller: loginController
      responses:
        '201':
          description: logged in
        '401':
          description: email or password does not match
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewUser'
        description: User to log in
  /tasks:
    get:
      tags:
        - tasks
      summary: queries current user's tasks
      operationId: taskQuery
      x-exegesis-controller: taskController
      parameters:
        - in: query
          name: userId
          description: Id of owning user
          required: false
          schema:
            type: string
            format: uuid
        - in: query
          name: startDate
          description: Start of date range for filtering
          required: false
          schema:
            type: string
            format: date
        - in: query
          name: endDate
          description: End of date range for filtering
          required: false
          schema:
            type: string
            format: date
      responses:
        '200':
          description: tasks matching criteria
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Task'
        '400':
          description: bad input parameter
        '403':
          description: forbidden
    post:
      tags:
        - tasks
      summary: creates tasks
      operationId: taskPost
      x-exegesis-controller: taskController
      responses:
        '201':
          description: task created
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Task'
        description: task to add
  '/tasks/{taskId}':
    get:
      tags:
        - tasks
      summary: gets a single task
      operationId: taskGet
      x-exegesis-controller: taskController
      parameters:
        - in: path
          name: taskId
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: task
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '403':
          description: not allowed
        '404':
          description: not found
    put:
      tags:
        - tasks
      summary: update a task
      operationId: taskPut
      x-exegesis-controller: taskController
      parameters:
        - in: path
          name: taskId
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: task
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '403':
          description: not allowed
        '404':
          description: not found
    delete:
      tags:
        - tasks
      summary: delete a task
      operationId: taskDelete
      x-exegesis-controller: taskController
      parameters:
        - in: path
          name: taskId
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: task deleted
        '403':
          description: not allowed
        '404':
          description: not found
components:
  schemas:
    User:
      type: object
      required:
        - id
        - email
      properties:
        id:
          type: string
          format: uuid
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
        email:
          type: string
          format: email
          example: user@app.com
        preferredDailyHours:
          type: integer
          format: int32
          minimum: 0
          maximum: 24
    NewUser:
      type: object
      required:
        - email
        - plaintextPassword
      properties:
        email:
          type: string
          format: email
          example: user@app.com
        plaintextPassword:
          type: string
    Task:
      type: object
      required:
        - userId
        - date
        - duration
      properties:
        id:
          type: string
          format: uuid
        userId:
          type: string
          format: uuid
        date:
          type: string
          format: date
        duration:
          type: integer
          format: int32
          minimum: 0