info:
  title: QQQ API
  description: This is your api description!
  ## termsOfService: https://swagger.io/terms/
  contact:
    email: contact@kingsrook.com
  version: 0.0.1
#externalDocs:
#  description: Find out more at
#  url: https://swagger.io
servers:
  - description: Localhost development
    url: http://localhost:8000/api/
tags:
  - name: person
    description: Operations on the Person table.
paths:
  /person/query:
    get:
      summary: Search the Person table using multiple query string fields.
      description: |
        Returns Person records matching the query parameters.<br/>
        Each query field can be supplied multiple times to add additional criteria.<br/>
        Query values can be prefixed with an operator (=, <, <=, >, >=, IN, MATCHES, EMPTY, BETWEEN).  The default operator if only a value is given is =.<br/>
        Operators can be prefixed with a ! to be negated.<br/>
        Operators which are a word (IN, MATCHES, EMPTY, BETWEEN) must be followed by a space.<br/>
        Values for operators which take multiple values (IN, BETWEEN) must be comma delimited.<br/>
      operationId: queryPerson
      tags: [person]
      parameters:
        - name: pageNo
          description: Which page of results to return.  Starts at 1.
          in: query
          schema:
            type: integer
        - name: pageSize
          description: Max number of records to include in a page.  Defaults to 50.
          in: query
          schema:
            type: integer
        - name: includeCount
          in: query
          description: |
            Whether or not to include the count (total matching records) in the result.<br/>
            In some situations, counts can slow down queries, in which case you may want to specify includeCount=false.<br/>
            Default is true.<br/>
          schema:
            type: boolean
        - name: booleanOperator
          in: query
          description: Whether to join query field as an AND or an OR.  Default is AND.
          schema:
            type: string
            enum: ["AND", "OR"]
        - name: orderBy
          in: query
          schema:
            type: string
          examples:
            id:
              summary: order by id (by default, is ascending)
              value: id
            idDesc:
              summary: order by id descending
              value: id asc
            idAsc:
              summary: order by id ascending (explicitly specified)
              value: id asc
            stateCity:
              summary: order by state, then by city (both ascending)
              value: state, city
            ratingPriceSku:
              summary: rating descending, then price ascending, then sku
              value: rating desc, price asc, sku
        - name: id
          in: query
          description: Query on the id field.  Can prefix value with an operator, else defaults to = (equals).
          schema:
            type: array
            items:
              type: string
          explode: true
          examples:
            equals47:
              $ref: "#/components/examples/equals47"
            between42and47:
              $ref: "#/components/examples/between42and47"
            multiple:
              $ref: "#/components/examples/multipleNumbers"
        - name: firstName
          in: query
          description: Query on the firstName field.  Can prefix value with an operator, else defaults to = (equals).
          schema:
            type: array
            items:
              type: string
          examples:
            equalsJohn:
              $ref: "#/components/examples/equalsJohn"
            inJohnPaul:
              $ref: "#/components/examples/inJohnPaul"
            multipleStrings:
              $ref: "#/components/examples/multipleStrings"
          explode: true
        - name: lastName
          in: query
          description: Query on the lastName field.  Can prefix value with an operator, else defaults to = (equals).
          schema:
            type: array
            items:
              type: string
          examples:
            equalsJohn:
              $ref: "#/components/examples/equalsJohn"
            inJohnPaul:
              $ref: "#/components/examples/inJohnPaul"
            multipleStrings:
              $ref: "#/components/examples/multipleStrings"
          explode: true
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/personSearchResult"
          description: Successfully searched Person table (though may have found 0 records).
        400:
          $ref: "#/components/responses/400"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        500:
          $ref: "#/components/responses/500"
    post:
      summary: Search the Person table using a posted query object
      description: |
        Returns Person records matching the query parameters.
      operationId: queryPerson
      tags: [person]
      requestBody:
        required: true
        description: |
          List of search fields from the person table.
          Each field must include its operator, and per operator, 0 or more values, always specified as an array.
          Fields may appear multiple times.  All fields will be combined using the specified (query parameter) booleanOperator.
        content:
          application/json:
            schema:
              type: object
              properties:
                booleanOperator:
                  description: Whether to join query field as an AND or an OR.  Default is AND.
                  type: string
                  enum: ["AND", "OR"]
                criteria:
                  type: array
                  items:
                    type: object
                    properties:
                      fieldName:
                        type: string
                      operator:
                        type: string
                        enum: [EQUALS, NOT_EQUALS, etc]
                      values:
                        type: array
                        items:
                          type: string
                  ## todo - subfilters!!
              example:
                - fieldName: firstName
                  operator: EQUALS
                  values: ["John"]
                - fieldName: id
                  operator: IN
                  values: [1,2,3]
      parameters:
        - name: pageNo
          description: Which page of results to return.  Starts at 1.
          in: query
          schema:
            type: integer
        - name: pageSize
          description: Max number of records to include in a page.  Defaults to 50.
          in: query
          schema:
            type: integer
        - name: includeCount
          in: query
          description: |
            Whether or not to include the count (total matching records) in the result.<br/>
            In some situations, counts can slow down queries, in which case you may want to specify includeCount=false.<br/>
            Default is true.<br/>
          schema:
            type: boolean
        - name: booleanOperator
          in: query
          description: Whether to join query field as an AND or an OR.  Default is AND.
          schema:
            type: string
            enum: ["AND", "OR"]
        - name: orderBy
          in: query
          schema:
            type: string
          examples:
            id:
              summary: order by id (by default, is ascending)
              value: id
            idDesc:
              summary: order by id descending
              value: id asc
            idAsc:
              summary: order by id ascending (explicitly specified)
              value: id asc
            stateCity:
              summary: order by state, then by city (both ascending)
              value: state, city
            ratingPriceSku:
              summary: rating descending, then price ascending, then sku
              value: rating desc, price asc, sku
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/personSearchResult"
          description: Successfully searched Person table (though may have found 0 records).
        400:
          $ref: "#/components/responses/400"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        500:
          $ref: "#/components/responses/500"
##   /person/filter:
##     get:
##       summary: Search the Person table using an OData style $filter parameter
##       description: Returns Person records matching the query parameters
##       operationId: filterPerson
##       responses:
##         200:
##           description: Successfully searched Person table (though may have 0 results)
##       parameters:
##         - name: $filter
##           in: query
##           schema:
##             type: string
##             items:
##               type: string
##           description: OData $filter style query string for Person records.  See https://some.com/filter for info
##           examples:
##             simple:
##               summary: id equals 42
##               value: id eq 42
##             complex:
##               summary: id equals 42 and firstName like 'Jo%'
##               value: id gt 47 and firstName like 'Jo%'
##       tags:
##         - person
  /person/{id}:
    get:
      summary: Find Person by Id
      description: Returns a single Person
      operationId: getPerson
      responses:
        200:
          description: Successfully got Person
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/person"
        400:
          $ref: "#/components/responses/400"
        401:
          $ref: "#/components/responses/401"
        404:
          $ref: "#/components/responses/404"
        403:
          $ref: "#/components/responses/403"
        500:
          $ref: "#/components/responses/500"
      parameters:
        - schema:
            type: integer
          in: path
          name: id
          description: Id of Person to return
          required: true
      tags:
        - person
    patch:
      summary: Update one Person
      description: Updates one Person record
      operationId: updatePerson
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/personWithoutId"
      parameters:
        - schema:
            type: integer
          in: path
          name: id
          description: Id of Person to update
          required: true
      responses:
        200:
          description: Successfully updated Person
      tags:
        - person
    delete:
      summary: Delete one Person
      description: Deletes one Person record
      operationId: deletePerson
      responses:
        200:
          description: Successfully deleted Person
      tags:
        - person
  /person/:
    post:
      summary: Create one Person
      description: Creates a single Person record
      operationId: createPerson
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/personWithoutId"
      responses:
        201:
          description: Created.  The person has been created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    example: 1701
                    description: Generated id for the person that was inserted.
        400:
          $ref: "#/components/responses/400"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        500:
          $ref: "#/components/responses/500"
      tags:
        - person
  /person/bulk:
    patch:
      summary: Update multiple Person records
      description: Update multiple Person records
      operationId: bulkUpdatePerson
      requestBody:
        content:
          application/json:
            example:
              - id: 1701
                firstName: John
              - id: 1702
                lastName: McCartney
            schema:
              type: array
              items:
                $ref: "#/components/schemas/person"
      responses:
        207:
          description: Multi-Status.  See body for status of individual records.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    statusCode:
                      type: integer
                      description: HTTP status code for the record at this index.
                      example: 201
                    statusMessage:
                      type: string
                      description: HTTP status message for the record at this index.
                      example: Created
                    id:
                      type: integer
                      description: Generated id, if applicable, for the record at this index.
                      example: 1701
                    error:
                      type: string
                      description: Additional error details, if applicable, for the record at this index.
                      example: "Missing required field: firstName"
                example:
                  - statusCode: 200
                    statusMessage: OK
                  - statusCode: 400
                    statusMessage: Bad Request
                    error: "Record cannot be deleted due to foreign key check"
                  - statusCode: 500
                    statusMessage: Internal Server Error
                    error: Error connecting to database
        400:
          $ref: "#/components/responses/400"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        500:
          $ref: "#/components/responses/500"
      tags:
        - person
    delete:
      summary: Delete multiple Person records
      description: Deletes multiple Person records
      operationId: bulkDeletePerson
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                 type: integer
                 description: ids of the person records to be deleted
              example: [42, 47]
      responses:
        207:
          description: Multi-Status.  See body for status of individual records.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    statusCode:
                      type: integer
                      description: HTTP status code for the record at this index.
                      example: 201
                    statusMessage:
                      type: string
                      description: HTTP status message for the record at this index.
                      example: Created
                    id:
                      type: integer
                      description: Generated id, if applicable, for the record at this index.
                      example: 1701
                    error:
                      type: string
                      description: Additional error details, if applicable, for the record at this index.
                      example: "Missing required field: firstName"
                example:
                  - statusCode: 201
                    statusMessage: Created
                    id: 1701
                  - statusCode: 400
                    statusMessage: Bad Request
                    error: "Missing value for required field:  firstName"
                  - statusCode: 500
                    statusMessage: Internal Server Error
                    error: Error connecting to database
        400:
          $ref: "#/components/responses/400"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        500:
          $ref: "#/components/responses/500"
      tags:
        - person
    post:
      summary: Create multiple Person records
      description: Creates multiple Person records
      operationId: bulkCreatePerson
      requestBody:
        content:
          application/json:
            example:
              - firstName: John
                lastName: Lennon
              - firstName: Paul
                lastName: McCartney
              - firstName: George
                lastName: Harrison
            schema:
              type: array
              items:
                $ref: "#/components/schemas/personWithoutId"
      responses:
        207:
          description: Multi-Status.  See body for status of individual records.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    statusCode:
                      type: integer
                      description: HTTP status code for the record at this index.
                      example: 201
                    statusMessage:
                      type: string
                      description: HTTP status message for the record at this index.
                      example: Created
                    id:
                      type: integer
                      description: Generated id, if applicable, for the record at this index.
                      example: 1701
                    error:
                      type: string
                      description: Additional error details, if applicable, for the record at this index.
                      example: "Missing required field: firstName"
                example:
                  - statusCode: 201
                    statusMessage: Created
                    id: 1701
                  - statusCode: 400
                    statusMessage: Bad Request
                    error: "Missing value for required field:  firstName"
                  - statusCode: 500
                    statusMessage: Internal Server Error
                    error: Error connecting to database
        400:
          $ref: "#/components/responses/400"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        500:
          $ref: "#/components/responses/500"
      tags:
        - person
components:
  examples:
    equals47:
      summary: equal to 47
      value:
        - "47"
    between42and47:
      summary: between 42 and 47
      value:
        - BETWEEN 42,47
    multipleNumbers:
      summary: between 42 and 47 and not equal to 45
      value:
        - BETWEEN 42,47
        - "!=45"
    equalsJohn:
      summary: equal to "John"
      value:
        - "John"
    inJohnPaul:
      summary: in ("John", "Paul")
      value:
        - IN ("John","Paul")
    multipleStrings:
      summary: matches R* and is not Ringo
      value:
        - MATCHES R*
        - "!=Ringo"
  schemas:
    personWithoutId:
      type: object
      properties:
        firstName:
          type: string
          description: First Name of the person.
          example: John
        lastName:
          type: string
          description: Last Name of the person.
          example: Lennon
    person:
      type: object
      properties:
        id:
          type: integer
          description: Id for the person.  Primary Key.
          example: 47
      allOf:
        - $ref: "#/components/schemas/personWithoutId"
    city:
      type: object
      properties:
        id:
          type: integer
          description: Id for the city.  Primary Key.
          example: 47
        state:
          type: string
          description: State of the city.
          example: MO
#      allOf:
#        - $ref: "#/components/schemas/personWithoutId"
    baseSearchResultFields:
      type: object
      properties:
        count:
          type: integer
          description: Number of records that matched the search criteria
        pageNo:
          type: integer
          description: ...
        pageSize:
          type: integer
          description: ...
    personSearchResult:
      type: object
      allOf:
        - $ref: "#/components/schemas/baseSearchResultFields"
      properties:
        records:
          type: array
          items:
            allOf:
              - $ref: "#/components/schemas/person"
              - $ref: "#/components/schemas/personWithoutId"
  responses:
    401:
      description: Unauthorized.  The required authentication credentials were missing or invalid.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: The required authentication credentials were missing or invalid.
    403:
      description: Forbidden.  You do not have permission to access the requested resource.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Forbidden.  You do not have permission to access the requested resource.
    404:
      description: Not Found.  The requested record was not found.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Not Found.  The requested record was not found.
    400:
      description: Bad Request.  Some portion of the request's content was not acceptable to the server.  See error message in body for details.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: 'Parameter id should be given an integer value, but received string: "Foo"'
    500:
      description: Internal Server Error.  An error occurred in the server processing the request.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Database connection error.  Try again later.