hazza/Phraseanet
1
0
Fork 0
mirror of https://github.com/alchemy-fr/Phraseanet.git synced 2025-10-10 11:33:17 +00:00
Code Issues Packages Projects Releases Wiki Activity

PHRAS-3153_Doc-to-Swagger

Browse Source 
- add: json examples for post/patch record
[ci skip]
This commit is contained in:
jygaulier
2021-02-08 21:18:17 +01:00
parent 58f303547a
commit 63018e417e
3 changed files with 859 additions and 600 deletions
Download Patch File Download Diff File Expand all files Collapse all files

975
API_documentation/v3/_compiled.yaml
View File

File diff suppressed because it is too large Load Diff

482
API_documentation/v3/api.yaml
View File

@@ -244,50 +244,6 @@ paths:
$ref: 'responses.yaml#/error_response' $ref: 'responses.yaml#/error_response'
# ------------ record ----------- # ------------ 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}': '/records/{sbas_id}/{record_id}':
get: get:
tags: tags:
@@ -309,6 +265,444 @@ paths:
description: Record not found description: Record not found
default: default:
$ref: 'responses.yaml#/error_response' $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': '/stories/{sbas_id}/{record_id}/children':
get: get:
tags: tags:

2
API_documentation/v3/schemas.yaml
View File

@@ -15,6 +15,8 @@ RecordPatch_metadata:
value: value:
# todo : change to string, int, number, array # todo : change to string, int, number, array
type: string type: string
RecordPatch_status: RecordPatch_status:
type: object type: object
required: required: