mirror of
https://github.com/Kingsrook/qqq.git
synced 2025-07-20 22:18:43 +00:00
Initial checkin of qqq-middleware-api
This commit is contained in:
676
qqq-middleware-api/src/test/resources/person-many-endpoints.yaml
Normal file
676
qqq-middleware-api/src/test/resources/person-many-endpoints.yaml
Normal file
@ -0,0 +1,676 @@
|
||||
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.
|
||||
Reference in New Issue
Block a user