mirror of
https://github.com/alchemy-fr/Phraseanet.git
synced 2025-10-08 10:34:34 +00:00
PHRAS-3153_Doc-to-Swagger
- add: json examples for post/patch record [ci skip]
This commit is contained in:
jygaulier
File diff suppressed because it is too large
Load Diff
@@ -244,50 +244,6 @@ paths:
|
||||
$ref: 'responses.yaml#/error_response'
|
||||
|
||||
# ------------ record -----------
|
||||
'/records/{base_id}':
|
||||
post:
|
||||
tags:
|
||||
- record
|
||||
summary: Creates a record
|
||||
description: 'Creates a single record, including document and/or data.'
|
||||
operationId: createRecord
|
||||
parameters:
|
||||
- name: base_id
|
||||
in: path
|
||||
description: ID of the base
|
||||
required: true
|
||||
schema:
|
||||
$ref: schemas.yaml#/ID
|
||||
requestBody:
|
||||
content:
|
||||
multipart/form-data:
|
||||
schema:
|
||||
description: 'to create a record with a file (document)'
|
||||
type: object
|
||||
properties:
|
||||
body:
|
||||
$ref: schemas.yaml#/RecordPatch
|
||||
file:
|
||||
description : 'uploaded file'
|
||||
type: string
|
||||
format: binary
|
||||
application/json:
|
||||
schema:
|
||||
description: 'to create a record without file (document)'
|
||||
allOf:
|
||||
- $ref: schemas.yaml#/RecordPatch
|
||||
responses:
|
||||
200:
|
||||
description: ok
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: schemas.yaml#/ApiResponse_record
|
||||
default:
|
||||
$ref: 'responses.yaml#/error_response'
|
||||
# security:
|
||||
# - api_key: []
|
||||
|
||||
'/records/{sbas_id}/{record_id}':
|
||||
get:
|
||||
tags:
|
||||
@@ -309,6 +265,444 @@ paths:
|
||||
description: Record not found
|
||||
default:
|
||||
$ref: 'responses.yaml#/error_response'
|
||||
|
||||
'/records/{base_id}':
|
||||
post:
|
||||
tags:
|
||||
- record
|
||||
summary: Creates a record
|
||||
description: |
|
||||
Creates a single record, including document and/or data.
|
||||
|
||||
### To create a record __with__ a file (document)
|
||||
|
||||
_Since multipart is required to pass a file, json data must be passed as a part named "body"_
|
||||
|
||||
### To create a record __without__ file
|
||||
|
||||
_Since no file is passed, data can be passed as plain body_
|
||||
|
||||
### metadata / status-bits setting
|
||||
|
||||
see "PATCH" method for examples, apply only relevant "set" operation on just created record with empty data.
|
||||
|
||||
operationId: createRecord
|
||||
parameters:
|
||||
- name: base_id
|
||||
in: path
|
||||
description: ID of the base
|
||||
required: true
|
||||
schema:
|
||||
$ref: schemas.yaml#/ID
|
||||
requestBody:
|
||||
content:
|
||||
multipart/form-data:
|
||||
schema:
|
||||
description: to create a record __with__ a file (document)
|
||||
type: object
|
||||
properties:
|
||||
body:
|
||||
$ref: schemas.yaml#/RecordPatch
|
||||
file:
|
||||
description : 'uploaded file'
|
||||
type: string
|
||||
format: binary
|
||||
application/json:
|
||||
schema:
|
||||
description: To create a record __without__ file
|
||||
allOf:
|
||||
- $ref: schemas.yaml#/RecordPatch
|
||||
responses:
|
||||
200:
|
||||
description: ok
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: schemas.yaml#/ApiResponse_record
|
||||
default:
|
||||
$ref: 'responses.yaml#/error_response'
|
||||
# security:
|
||||
# - api_key: []
|
||||
|
||||
'/records/{sbas_id}/{record_id}/setmetadatas':
|
||||
patch:
|
||||
tags:
|
||||
- record
|
||||
summary: Set or change metadata and/or status-bits of a record
|
||||
description: |
|
||||
Set or change metadata and/or status-bits of a record.
|
||||
|
||||
Data is sent as json in the BODY of the request.
|
||||
|
||||
* metadatas is an array of simple “actions” that are applied in the same order as defined into json.
|
||||
* field can be specified by meta_struct_id or by name
|
||||
* field value (when relevant) can be specified by meta_id or by actual value
|
||||
* method to match a value can be (strict | ignore-case | regexp); default is “ignore-case”
|
||||
* to act on multi-values we must set an “action” (set | add | delete | replace); default is “set”
|
||||
* default action “set” and special value (null, arrays) allow to write simplified actions
|
||||
* the “replace” action is useful to set/add values only if a value already exists
|
||||
|
||||
# Body examples :
|
||||
|
||||
## mono-valued fields
|
||||
|
||||
set a mono-value field by its meta_struct_id
|
||||
|
||||
```json
|
||||
{
|
||||
"metadatas": [
|
||||
{
|
||||
"meta_struct_id": 1,
|
||||
"action": "set",
|
||||
"value": "A pretty string"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
same thing (because default action is “set”), by field name
|
||||
|
||||
```
|
||||
{
|
||||
"metadatas": [
|
||||
{
|
||||
"field_name": "Author",
|
||||
"value": "John Doe"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
delete a mono-valued field
|
||||
|
||||
```
|
||||
{
|
||||
"metadatas": [
|
||||
{
|
||||
"field_name": "Copyright",
|
||||
"action": "delete"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
same thing
|
||||
|
||||
```
|
||||
{
|
||||
"metadatas": [
|
||||
{
|
||||
"field_name": "Copyright",
|
||||
"value": null
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## multi-valued
|
||||
|
||||
replace a keyword __if we know its meta-id__
|
||||
|
||||
```
|
||||
{
|
||||
"metadatas": [
|
||||
{
|
||||
"field_name": "Keywords",
|
||||
"meta_id": 678,
|
||||
"value": "Dog"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
delete a specific keyword by its meta-id (we could also set action : “delete”, omit value, …)
|
||||
|
||||
```
|
||||
{
|
||||
"metadatas": [
|
||||
{
|
||||
"field_name": "Keywords",
|
||||
"meta_id": 345,
|
||||
"value": null
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
delete a specific keyword by its value. Since we must pass the value (not null), we must set the action “delete”
|
||||
|
||||
_nb_ : the default matching method is “ignore-case” so we can write the actual value all small letters
|
||||
|
||||
```
|
||||
{
|
||||
"metadatas": [
|
||||
{
|
||||
"field_name": "Keywords",
|
||||
"action": "delete",
|
||||
"value": "doggy"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
delete __all Keywords__
|
||||
|
||||
```
|
||||
{
|
||||
"metadatas": [
|
||||
{
|
||||
"field_name": "Keywords",
|
||||
"value": null
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
add a keyword
|
||||
|
||||
```
|
||||
{
|
||||
"metadatas": [
|
||||
{
|
||||
"field_name": "Keywords",
|
||||
"action": "add",
|
||||
"value": "Cat"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
replace all keywords by new ones
|
||||
|
||||
```
|
||||
{
|
||||
"metadatas": [
|
||||
{
|
||||
"field_name": "Keywords",
|
||||
"value": null
|
||||
},
|
||||
{
|
||||
"field_name": "Keywords",
|
||||
"action": "add",
|
||||
"value": "Cat"
|
||||
},
|
||||
{
|
||||
"field_name": "Keywords",
|
||||
"action": "add",
|
||||
"value": "Dog"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
same thing using an array
|
||||
|
||||
```
|
||||
{
|
||||
"metadatas": [
|
||||
{
|
||||
"field_name": "Keywords",
|
||||
"value": [
|
||||
"Dog",
|
||||
"Cat",
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
simplification of multiple same actions with arrays as value
|
||||
|
||||
```
|
||||
{
|
||||
"metadatas": [
|
||||
{
|
||||
"field_name": "Keywords",
|
||||
"action": "delete",
|
||||
"value": [
|
||||
"cop",
|
||||
"bobby",
|
||||
"pig",
|
||||
"nicks"
|
||||
]
|
||||
},
|
||||
{
|
||||
"field_name": "Keywords",
|
||||
"action": "add",
|
||||
"value": [
|
||||
"Policeman",
|
||||
"Arrest"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
replacing a keyword by value can be 2 actions if we know that the bad value exists…
|
||||
|
||||
```
|
||||
{
|
||||
"metadatas": [
|
||||
{
|
||||
"field_name": "Keywords",
|
||||
"action": "delete",
|
||||
"value": "cop"
|
||||
},
|
||||
{
|
||||
"field_name": "Keywords",
|
||||
"action": "add",
|
||||
"value": "Policeman"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
replace-if-exists
|
||||
|
||||
…but we can also use the “replace” action if we are not sure
|
||||
|
||||
```
|
||||
{
|
||||
"metadatas": [
|
||||
{
|
||||
"field_name": "Keywords",
|
||||
"action": "replace",
|
||||
"value": "cop",
|
||||
"replace_with": "Policeman"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
fix spelling errors with regexp
|
||||
|
||||
```
|
||||
{
|
||||
"metadatas": [
|
||||
{
|
||||
"field_name": "Persons",
|
||||
"action": "replace",
|
||||
"match_method": "regexp",
|
||||
"value": "/joh?nn?[i|y]\w+hall?[i|y]day/\w+in\w([0-9]{4})/i",
|
||||
"replace_with": "Johnny Halliday in $1"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
add translations for existing keywords (using “replace”)
|
||||
|
||||
_nb_ : multi-values are kept unique so double replacement is not a pb.
|
||||
|
||||
```
|
||||
{
|
||||
"metadatas": [
|
||||
{
|
||||
"field_name": "Keywords",
|
||||
"action": "replace",
|
||||
"value": "dog",
|
||||
"replace_with": [
|
||||
"Dog",
|
||||
"Chien"
|
||||
]
|
||||
},
|
||||
{
|
||||
"field_name": "Keywords",
|
||||
"action": "replace",
|
||||
"value": "chien",
|
||||
"replace_with": [
|
||||
"Dog",
|
||||
"Chien"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
same thing using regexp
|
||||
|
||||
```
|
||||
{
|
||||
"metadatas": [
|
||||
{
|
||||
"field_name": "Keywords",
|
||||
"action": "replace",
|
||||
"value": "/cop|bobby|pig|flic/i",
|
||||
"match_method": "regexp",
|
||||
"replace_with": [
|
||||
"Policeman",
|
||||
"Policier"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Status-bits
|
||||
|
||||
sb can be changed with the same api.
|
||||
|
||||
To not get confused with "names", sb are referenced by bit number only 4…31
|
||||
|
||||
```
|
||||
{
|
||||
"metadatas": [
|
||||
...
|
||||
],
|
||||
"status": [
|
||||
{
|
||||
"bit": 4,
|
||||
"state": true
|
||||
},
|
||||
{
|
||||
"bit": 5,
|
||||
"state": false
|
||||
},
|
||||
{
|
||||
"bit": 6,
|
||||
"state": false
|
||||
},
|
||||
{
|
||||
"bit": 7,
|
||||
"state": false
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
operationId: patchRecord
|
||||
parameters:
|
||||
- name: sbas_id
|
||||
in: path
|
||||
description: ID of the sbas
|
||||
required: true
|
||||
schema:
|
||||
$ref: schemas.yaml#/ID
|
||||
- name: record_id
|
||||
in: path
|
||||
description: ID of the record
|
||||
required: true
|
||||
schema:
|
||||
$ref: schemas.yaml#/ID
|
||||
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
allOf:
|
||||
- $ref: schemas.yaml#/RecordPatch
|
||||
responses:
|
||||
200:
|
||||
description: ok
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: schemas.yaml#/ApiResponse_record
|
||||
default:
|
||||
$ref: 'responses.yaml#/error_response'
|
||||
|
||||
|
||||
'/stories/{sbas_id}/{record_id}/children':
|
||||
get:
|
||||
tags:
|
||||
|
||||
@@ -15,6 +15,8 @@ RecordPatch_metadata:
|
||||
value:
|
||||
# todo : change to string, int, number, array
|
||||
type: string
|
||||
|
||||
|
||||
RecordPatch_status:
|
||||
type: object
|
||||
required:
|
||||
|
||||
Reference in New Issue
Block a user