Skip to content

Commit b1a9e12

Browse files
vitormattosvitormattos
committed
docs(openapi): add search endpoint to admin spec
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
1 parent 62e8608 commit b1a9e12

1 file changed

Lines changed: 297 additions & 0 deletions

File tree

‎openapi-administration.json‎

Lines changed: 297 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,21 @@
7979
}
8080
}
8181
},
82+
"LookupField": {
83+
"type": "object",
84+
"required": [
85+
"definition",
86+
"value"
87+
],
88+
"properties": {
89+
"definition": {
90+
"$ref": "#/components/schemas/Definition"
91+
},
92+
"value": {
93+
"$ref": "#/components/schemas/ValueRecord"
94+
}
95+
}
96+
},
8297
"OCSMeta": {
8398
"type": "object",
8499
"required": [
@@ -103,6 +118,65 @@
103118
}
104119
}
105120
},
121+
"SearchItem": {
122+
"type": "object",
123+
"required": [
124+
"user_uid",
125+
"display_name",
126+
"fields"
127+
],
128+
"properties": {
129+
"user_uid": {
130+
"type": "string"
131+
},
132+
"display_name": {
133+
"type": "string"
134+
},
135+
"fields": {
136+
"type": "object",
137+
"additionalProperties": {
138+
"$ref": "#/components/schemas/LookupField"
139+
}
140+
}
141+
}
142+
},
143+
"SearchResult": {
144+
"type": "object",
145+
"required": [
146+
"items",
147+
"pagination"
148+
],
149+
"properties": {
150+
"items": {
151+
"type": "array",
152+
"items": {
153+
"$ref": "#/components/schemas/SearchItem"
154+
}
155+
},
156+
"pagination": {
157+
"type": "object",
158+
"required": [
159+
"limit",
160+
"offset",
161+
"total"
162+
],
163+
"properties": {
164+
"limit": {
165+
"type": "integer",
166+
"format": "int64"
167+
},
168+
"offset": {
169+
"type": "integer",
170+
"format": "int64"
171+
},
172+
"total": {
173+
"type": "integer",
174+
"format": "int64"
175+
}
176+
}
177+
}
178+
}
179+
},
106180
"Type": {
107181
"type": "string",
108182
"enum": [
@@ -1343,6 +1417,229 @@
13431417
}
13441418
}
13451419
}
1420+
},
1421+
"/ocs/v2.php/apps/profile_fields/api/v1/users/search": {
1422+
"get": {
1423+
"operationId": "field_value_admin_api-search",
1424+
"summary": "Search users by one profile field filter",
1425+
"description": "Return a paginated list of users that match one explicit profile field filter. The response includes only the field/value pair that produced the match, not the full profile.\nThis endpoint requires admin access",
1426+
"tags": [
1427+
"field_value_admin_api"
1428+
],
1429+
"security": [
1430+
{
1431+
"bearer_auth": []
1432+
},
1433+
{
1434+
"basic_auth": []
1435+
}
1436+
],
1437+
"parameters": [
1438+
{
1439+
"name": "fieldKey",
1440+
"in": "query",
1441+
"description": "Immutable key of the field to filter by",
1442+
"required": true,
1443+
"schema": {
1444+
"type": "string"
1445+
}
1446+
},
1447+
{
1448+
"name": "operator",
1449+
"in": "query",
1450+
"description": "Explicit search operator, currently `eq` or `contains`",
1451+
"schema": {
1452+
"type": "string",
1453+
"default": "eq"
1454+
}
1455+
},
1456+
{
1457+
"name": "value",
1458+
"in": "query",
1459+
"description": "Value payload to compare against the stored field value",
1460+
"schema": {
1461+
"type": "string",
1462+
"nullable": true
1463+
}
1464+
},
1465+
{
1466+
"name": "limit",
1467+
"in": "query",
1468+
"description": "Maximum number of users to return in the current page",
1469+
"schema": {
1470+
"type": "integer",
1471+
"format": "int64",
1472+
"default": 50
1473+
}
1474+
},
1475+
{
1476+
"name": "offset",
1477+
"in": "query",
1478+
"description": "Zero-based offset into the matched result set",
1479+
"schema": {
1480+
"type": "integer",
1481+
"format": "int64",
1482+
"default": 0
1483+
}
1484+
},
1485+
{
1486+
"name": "OCS-APIRequest",
1487+
"in": "header",
1488+
"description": "Required to be true for the API request to pass",
1489+
"required": true,
1490+
"schema": {
1491+
"type": "boolean",
1492+
"default": true
1493+
}
1494+
}
1495+
],
1496+
"responses": {
1497+
"200": {
1498+
"description": "User search completed successfully",
1499+
"content": {
1500+
"application/json": {
1501+
"schema": {
1502+
"type": "object",
1503+
"required": [
1504+
"ocs"
1505+
],
1506+
"properties": {
1507+
"ocs": {
1508+
"type": "object",
1509+
"required": [
1510+
"meta",
1511+
"data"
1512+
],
1513+
"properties": {
1514+
"meta": {
1515+
"$ref": "#/components/schemas/OCSMeta"
1516+
},
1517+
"data": {
1518+
"$ref": "#/components/schemas/SearchResult"
1519+
}
1520+
}
1521+
}
1522+
}
1523+
}
1524+
}
1525+
}
1526+
},
1527+
"400": {
1528+
"description": "Invalid search filter or pagination values",
1529+
"content": {
1530+
"application/json": {
1531+
"schema": {
1532+
"type": "object",
1533+
"required": [
1534+
"ocs"
1535+
],
1536+
"properties": {
1537+
"ocs": {
1538+
"type": "object",
1539+
"required": [
1540+
"meta",
1541+
"data"
1542+
],
1543+
"properties": {
1544+
"meta": {
1545+
"$ref": "#/components/schemas/OCSMeta"
1546+
},
1547+
"data": {
1548+
"type": "object",
1549+
"required": [
1550+
"message"
1551+
],
1552+
"properties": {
1553+
"message": {
1554+
"type": "string"
1555+
}
1556+
}
1557+
}
1558+
}
1559+
}
1560+
}
1561+
}
1562+
}
1563+
}
1564+
},
1565+
"404": {
1566+
"description": "Search field definition not found",
1567+
"content": {
1568+
"application/json": {
1569+
"schema": {
1570+
"type": "object",
1571+
"required": [
1572+
"ocs"
1573+
],
1574+
"properties": {
1575+
"ocs": {
1576+
"type": "object",
1577+
"required": [
1578+
"meta",
1579+
"data"
1580+
],
1581+
"properties": {
1582+
"meta": {
1583+
"$ref": "#/components/schemas/OCSMeta"
1584+
},
1585+
"data": {
1586+
"type": "object",
1587+
"required": [
1588+
"message"
1589+
],
1590+
"properties": {
1591+
"message": {
1592+
"type": "string"
1593+
}
1594+
}
1595+
}
1596+
}
1597+
}
1598+
}
1599+
}
1600+
}
1601+
}
1602+
},
1603+
"401": {
1604+
"description": "Authenticated admin user is required",
1605+
"content": {
1606+
"application/json": {
1607+
"schema": {
1608+
"type": "object",
1609+
"required": [
1610+
"ocs"
1611+
],
1612+
"properties": {
1613+
"ocs": {
1614+
"type": "object",
1615+
"required": [
1616+
"meta",
1617+
"data"
1618+
],
1619+
"properties": {
1620+
"meta": {
1621+
"$ref": "#/components/schemas/OCSMeta"
1622+
},
1623+
"data": {
1624+
"type": "object",
1625+
"required": [
1626+
"message"
1627+
],
1628+
"properties": {
1629+
"message": {
1630+
"type": "string"
1631+
}
1632+
}
1633+
}
1634+
}
1635+
}
1636+
}
1637+
}
1638+
}
1639+
}
1640+
}
1641+
}
1642+
}
13461643
}
13471644
},
13481645
"tags": []

0 commit comments

Comments
 (0)