mirror of
https://github.com/alchemy-fr/Phraseanet.git
synced 2025-10-19 16:03:14 +00:00
PHRAS-3153_Doc-to-Swagger
- add extended mode to /record and /story - fix compilation in 1 file - better examples - todo : extended mode for /search - todo : check "include[]" available keys (compare with extended mode) - todo : remove 'id' type ?
This commit is contained in:
jygaulier
@@ -13,7 +13,7 @@ to update in swaggerhub (single file) :
|
||||
|
||||
- compile sources in a single file for swaggerhub (run from <phraseanet-dir>)
|
||||
|
||||
`swagger-cli bundle API_documentation/v3/api.yaml -o API_documentation/v3/_compiled.yaml -t yaml`
|
||||
`swagger-cli bundle API_documentation/v3/api.yaml -r -o API_documentation/v3/_compiled.yaml -t yaml`
|
||||
|
||||
|
||||
- copy/paste the generated content from `_compiled.yaml` to
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,4 +1,4 @@
|
||||
openapi: 3.0.0
|
||||
openapi: 3.0.3
|
||||
info:
|
||||
description: >
|
||||
This is the documentation of Phraseanet API (v3)
|
||||
@@ -82,7 +82,7 @@ components:
|
||||
per_page:
|
||||
name: per_page
|
||||
in: query
|
||||
description: number of results per page. Use along with "page"
|
||||
description: number of items per page. Use along with "page"
|
||||
required: false
|
||||
schema:
|
||||
type: integer
|
||||
@@ -93,7 +93,7 @@ components:
|
||||
offset:
|
||||
name: offset
|
||||
in: query
|
||||
description: offset in records count, from 0. Use along with "limit"
|
||||
description: offset in items unit count, from 0. Use along with "limit"
|
||||
required: false
|
||||
schema:
|
||||
type: integer
|
||||
@@ -103,7 +103,7 @@ components:
|
||||
limit:
|
||||
name: limit
|
||||
in: query
|
||||
description: number of results. Use along with "offset"
|
||||
description: number of items. Use along with "offset"
|
||||
required: false
|
||||
schema:
|
||||
type: integer
|
||||
@@ -213,7 +213,7 @@ paths:
|
||||
schema:
|
||||
$ref: 'search.yaml#/ApiResponse_search'
|
||||
default:
|
||||
$ref: 'responses.yaml#/error_response'
|
||||
$ref: 'common.yaml#/error_response'
|
||||
|
||||
# ---------------- searchraw ----------------
|
||||
'/searchraw':
|
||||
@@ -241,7 +241,7 @@ paths:
|
||||
schema:
|
||||
$ref: 'searchraw.yaml#/ApiResponse_searchraw'
|
||||
default:
|
||||
$ref: 'responses.yaml#/error_response'
|
||||
$ref: 'common.yaml#/error_response'
|
||||
|
||||
# ------------ record -----------
|
||||
'/records/{sbas_id}/{record_id}':
|
||||
@@ -251,6 +251,15 @@ paths:
|
||||
summary: Find record by sbas_id and record_id
|
||||
description: |
|
||||
Returns a single record, which can be a real record or a story (check `is_story`)
|
||||
|
||||
## About extended mode
|
||||
passing header `Accept: application/vnd.phraseanet.record-extended+json`
|
||||
will add/populate objects :
|
||||
- subdefs
|
||||
- status
|
||||
- metadata
|
||||
- dces
|
||||
|
||||
operationId: getRecordById
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/sbas_id'
|
||||
@@ -261,11 +270,14 @@ paths:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: schemas.yaml#/ApiResponse_record
|
||||
$ref: record.yaml#/ApiResponse_record
|
||||
'application/vnd.phraseanet.record-extended+json':
|
||||
schema:
|
||||
$ref: record.yaml#/ApiResponse_record_extended
|
||||
404:
|
||||
description: Record not found
|
||||
default:
|
||||
$ref: 'responses.yaml#/error_response'
|
||||
$ref: 'common.yaml#/error_response'
|
||||
|
||||
'/records/{base_id}':
|
||||
post:
|
||||
@@ -314,9 +326,9 @@ paths:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: schemas.yaml#/ApiResponse_record
|
||||
$ref: record.yaml#/ApiResponse_record
|
||||
default:
|
||||
$ref: 'responses.yaml#/error_response'
|
||||
$ref: 'common.yaml#/error_response'
|
||||
# security:
|
||||
# - api_key: []
|
||||
|
||||
@@ -684,9 +696,9 @@ paths:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: schemas.yaml#/ApiResponse_record
|
||||
$ref: record.yaml#/ApiResponse_record
|
||||
default:
|
||||
$ref: 'responses.yaml#/error_response'
|
||||
$ref: 'common.yaml#/error_response'
|
||||
|
||||
'/stories/{sbas_id}/{record_id}':
|
||||
get:
|
||||
@@ -696,7 +708,8 @@ paths:
|
||||
description: |
|
||||
Returns a single story
|
||||
|
||||
This is the __same__ parameters / result as _/records/..._, except that here the record __must__ be a story else 404 is returned
|
||||
This is the __same__ parameters / result as _/records/..._, (including "extended mode"),
|
||||
except that here the record __must__ be a story else 404 is returned
|
||||
|
||||
operationId: getStoryById
|
||||
parameters:
|
||||
@@ -708,11 +721,14 @@ paths:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: schemas.yaml#/ApiResponse_story
|
||||
$ref: record.yaml#/ApiResponse_story
|
||||
'application/vnd.phraseanet.record-extended+json':
|
||||
schema:
|
||||
$ref: record.yaml#/ApiResponse_story_extended
|
||||
404:
|
||||
description: Story not found (
|
||||
default:
|
||||
$ref: 'responses.yaml#/error_response'
|
||||
$ref: 'common.yaml#/error_response'
|
||||
|
||||
|
||||
'/stories/{sbas_id}/{record_id}/children':
|
||||
@@ -725,26 +741,18 @@ paths:
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/sbas_id'
|
||||
- $ref: '#/components/parameters/record_id'
|
||||
- name: page
|
||||
in: query
|
||||
description: page number (default 1)
|
||||
required: false
|
||||
schema:
|
||||
type: integer
|
||||
- name: per_page
|
||||
in: query
|
||||
description: number of children (records uri) per page (default 10)
|
||||
required: false
|
||||
schema:
|
||||
type: integer
|
||||
- $ref: '#/components/parameters/page'
|
||||
- $ref: '#/components/parameters/per_page'
|
||||
- $ref: '#/components/parameters/offset'
|
||||
- $ref: '#/components/parameters/limit'
|
||||
responses:
|
||||
200:
|
||||
description: ok
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: schemas.yaml#/ApiResponse_RecordsUriArray
|
||||
$ref: record.yaml#/ApiResponse_RecordsUriArray
|
||||
404:
|
||||
description: Story (record) not found
|
||||
default:
|
||||
$ref: 'responses.yaml#/error_response'
|
||||
$ref: 'common.yaml#/error_response'
|
||||
|
||||
@@ -1,20 +1,43 @@
|
||||
error_response:
|
||||
description: Any other error
|
||||
|
||||
ApiResponse_meta:
|
||||
type: object
|
||||
properties:
|
||||
api_version:
|
||||
type: string
|
||||
example:
|
||||
'3.0.0'
|
||||
request:
|
||||
type: string
|
||||
example:
|
||||
'GET|POST|... /api/v3/....'
|
||||
response_time:
|
||||
type: string
|
||||
format: date-time
|
||||
example:
|
||||
'2021-02-11T14:18:02+00:00'
|
||||
http_code:
|
||||
type: integer
|
||||
format: int32
|
||||
example:
|
||||
200
|
||||
error_type:
|
||||
type: string
|
||||
example:
|
||||
null
|
||||
error_message:
|
||||
type: string
|
||||
example:
|
||||
null
|
||||
error_details:
|
||||
type: string
|
||||
example:
|
||||
null
|
||||
charset:
|
||||
type: string
|
||||
example:
|
||||
'UTF-8'
|
||||
|
||||
Facet:
|
||||
type: object
|
||||
@@ -77,3 +100,14 @@
|
||||
|
||||
ID:
|
||||
type: integer
|
||||
|
||||
Metadata_value:
|
||||
type: object
|
||||
properties:
|
||||
meta_id:
|
||||
type: integer
|
||||
example: 1771
|
||||
value:
|
||||
type: string
|
||||
example: value_of_the_field
|
||||
|
||||
|
||||
@@ -2,13 +2,13 @@
|
||||
type: object
|
||||
properties:
|
||||
databox_id:
|
||||
$ref: 'common.yaml#/ID'
|
||||
type: integer
|
||||
example:
|
||||
2
|
||||
record_id:
|
||||
$ref: 'common.yaml#/ID'
|
||||
title:
|
||||
type: string
|
||||
original_name:
|
||||
type: string
|
||||
type: integer
|
||||
example:
|
||||
34
|
||||
updated_on:
|
||||
type: string
|
||||
format: date-time
|
||||
@@ -16,13 +16,67 @@
|
||||
type: string
|
||||
format: date-time
|
||||
collection_id:
|
||||
$ref: 'common.yaml#/ID'
|
||||
type: integer
|
||||
example:
|
||||
5
|
||||
base_id:
|
||||
$ref: 'common.yaml#/ID'
|
||||
type: integer
|
||||
example:
|
||||
14
|
||||
thumbnail:
|
||||
$ref: '#/Subdef'
|
||||
$ref: '#/Thumbnail'
|
||||
uuid:
|
||||
type: string
|
||||
example:
|
||||
'5b079f33-0851-4aec-a978-b7f8d7204e5a'
|
||||
|
||||
_record_extension_:
|
||||
type: object
|
||||
properties:
|
||||
subdefs:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/Subdef'
|
||||
status:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
bit:
|
||||
type: integer
|
||||
example: 4
|
||||
state:
|
||||
type: boolean
|
||||
example: false
|
||||
metadata:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
meta_structure_id:
|
||||
type: integer
|
||||
name:
|
||||
type: string
|
||||
labels:
|
||||
type: object
|
||||
additionalProperties:
|
||||
type: string
|
||||
example:
|
||||
fr: label_du_champ_en_français
|
||||
en: field_label_in_english
|
||||
value:
|
||||
oneOf:
|
||||
- $ref: 'common.yaml#/Metadata_value'
|
||||
- type: array
|
||||
items:
|
||||
$ref: 'common.yaml#/Metadata_value'
|
||||
dces:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
example:
|
||||
'_not_documented_TODO_'
|
||||
|
||||
|
||||
Record:
|
||||
allOf: # Combines the basic _Record_ and the records-only properties
|
||||
@@ -31,23 +85,58 @@
|
||||
properties:
|
||||
mime_type:
|
||||
type: string
|
||||
example:
|
||||
'image/jpeg'
|
||||
title:
|
||||
type: string
|
||||
example:
|
||||
'Sleepy cat'
|
||||
original_name:
|
||||
type: string
|
||||
example:
|
||||
'DSC_12345.jpg'
|
||||
technical_informations:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/TechnicalInformation'
|
||||
sha256:
|
||||
type: string
|
||||
example:
|
||||
'6f330ac0ae2...'
|
||||
phrasea_type:
|
||||
type: string
|
||||
enum:
|
||||
- image
|
||||
- video
|
||||
example:
|
||||
'image'
|
||||
is_story:
|
||||
type: boolean
|
||||
default: false
|
||||
|
||||
Record_extended:
|
||||
allOf:
|
||||
- $ref: '#/Record'
|
||||
- $ref: '#/_record_extension_'
|
||||
|
||||
Story:
|
||||
allOf: # Combines the basic _Record_ and the stories-only properties
|
||||
- $ref: '#/_Record_'
|
||||
- type: object
|
||||
properties:
|
||||
mime_type:
|
||||
type: string
|
||||
default: null
|
||||
title:
|
||||
type: string
|
||||
example:
|
||||
'sans-titre'
|
||||
original_name:
|
||||
type: string
|
||||
default: null
|
||||
is_story:
|
||||
type: boolean
|
||||
default: true
|
||||
children_offset:
|
||||
type: integer
|
||||
description: 'Children pagination offset ; Always 0'
|
||||
@@ -71,13 +160,23 @@
|
||||
items:
|
||||
$ref: '#/Record'
|
||||
|
||||
Story_extended:
|
||||
allOf:
|
||||
- $ref: '#/Story'
|
||||
- $ref: '#/_record_extension_'
|
||||
|
||||
|
||||
|
||||
TechnicalInformation:
|
||||
type: object
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
value:
|
||||
additionalProperties:
|
||||
type: string
|
||||
example:
|
||||
Aperture: 6.3
|
||||
CameraModel: 'Canon EOS 5D Mark II'
|
||||
Channels: 3
|
||||
ColorSpace: RGB
|
||||
FileSize: 5618218
|
||||
|
||||
Subdef:
|
||||
type: object
|
||||
@@ -107,6 +206,7 @@
|
||||
type: string
|
||||
substituted:
|
||||
type: boolean
|
||||
example: false
|
||||
created_on:
|
||||
type: string
|
||||
format: date-time
|
||||
@@ -117,3 +217,77 @@
|
||||
type: string
|
||||
url_ttl:
|
||||
type: integer
|
||||
example: 7200
|
||||
|
||||
Thumbnail:
|
||||
allOf:
|
||||
- type: object
|
||||
properties:
|
||||
name:
|
||||
example: 'thumbnail'
|
||||
mime_type:
|
||||
example: 'image/jpeg'
|
||||
height:
|
||||
example: 160
|
||||
width:
|
||||
example: 240
|
||||
filesize:
|
||||
example: 2375
|
||||
url:
|
||||
example: 'http://phraseanet.demo.fr/medias/eyJ0eXAiOiJKV1Q...'
|
||||
- $ref: '#/Subdef'
|
||||
|
||||
ApiResponse_record:
|
||||
type: object
|
||||
properties:
|
||||
meta:
|
||||
$ref: 'common.yaml#/ApiResponse_meta'
|
||||
response:
|
||||
$ref: '#/Record'
|
||||
|
||||
ApiResponse_record_extended:
|
||||
type: object
|
||||
properties:
|
||||
meta:
|
||||
$ref: 'common.yaml#/ApiResponse_meta'
|
||||
response:
|
||||
$ref: '#/Record_extended'
|
||||
|
||||
ApiResponse_story:
|
||||
type: object
|
||||
properties:
|
||||
meta:
|
||||
$ref: 'common.yaml#/ApiResponse_meta'
|
||||
response:
|
||||
$ref: '#/Story'
|
||||
|
||||
ApiResponse_story_extended:
|
||||
type: object
|
||||
properties:
|
||||
meta:
|
||||
$ref: 'common.yaml#/ApiResponse_meta'
|
||||
response:
|
||||
$ref: '#/Story_extended'
|
||||
|
||||
|
||||
# for "/stories/{sbas_id}/{record_id}/children"
|
||||
RecordUri:
|
||||
type: string
|
||||
example: '/api/v3/records/1/48'
|
||||
|
||||
RecordsUriArray:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/RecordUri'
|
||||
example:
|
||||
- '/api/v3/records/1/48'
|
||||
- '/api/v3/records/1/49'
|
||||
- '/api/v3/records/1/50'
|
||||
ApiResponse_RecordsUriArray:
|
||||
type: object
|
||||
properties:
|
||||
meta:
|
||||
$ref: 'common.yaml#/ApiResponse_meta'
|
||||
response:
|
||||
$ref: '#/RecordsUriArray'
|
||||
|
||||
|
||||
@@ -1,15 +0,0 @@
|
||||
record_response:
|
||||
type: object
|
||||
properties:
|
||||
200:
|
||||
description: successful operation
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: schemas.yaml#/ApiResponse_record
|
||||
400:
|
||||
description: Any other error
|
||||
404:
|
||||
description: Record not found
|
||||
error_response:
|
||||
description: Any other error
|
||||
@@ -41,94 +41,9 @@ RecordPatch:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/RecordPatch_status'
|
||||
ApiResponse_meta:
|
||||
type: object
|
||||
properties:
|
||||
api_version:
|
||||
type: string
|
||||
request:
|
||||
type: string
|
||||
response_time:
|
||||
type: string
|
||||
format: date-time
|
||||
http_code:
|
||||
type: integer
|
||||
format: int32
|
||||
error_type:
|
||||
type: string
|
||||
error_message:
|
||||
type: string
|
||||
ApiResponse_record:
|
||||
type: object
|
||||
properties:
|
||||
meta:
|
||||
$ref: '#/ApiResponse_meta'
|
||||
response:
|
||||
$ref: 'record.yaml#/Record'
|
||||
ApiResponse_story:
|
||||
type: object
|
||||
properties:
|
||||
meta:
|
||||
$ref: '#/ApiResponse_meta'
|
||||
response:
|
||||
$ref: 'record.yaml#/Story'
|
||||
|
||||
# -------------------- searchraw ---------------
|
||||
|
||||
# -------------------- search ---------------
|
||||
ApiResponse_search:
|
||||
type: object
|
||||
properties:
|
||||
meta:
|
||||
$ref: '#/ApiResponse_meta'
|
||||
response:
|
||||
$ref: '#/ApiResponse_search_response'
|
||||
ApiResponse_search_response:
|
||||
type: object
|
||||
properties:
|
||||
offset:
|
||||
type: integer
|
||||
description: 'Pagination offset as passed (or computed from "page/per_page") in request'
|
||||
limit:
|
||||
type: integer
|
||||
description: 'Pagination limit as passed in request'
|
||||
count:
|
||||
type: integer
|
||||
description: 'Number of results in this page [0...limit]'
|
||||
total:
|
||||
type: integer
|
||||
description: 'Total number of results'
|
||||
minimum: 1
|
||||
results:
|
||||
type: object
|
||||
properties:
|
||||
stories:
|
||||
type: array
|
||||
items:
|
||||
$ref: 'record.yaml#/Story'
|
||||
records:
|
||||
type: array
|
||||
items:
|
||||
$ref: 'record.yaml#/Record'
|
||||
facets:
|
||||
$ref: 'common.yaml#/FacetsArray'
|
||||
|
||||
|
||||
|
||||
RecordUri:
|
||||
type: string
|
||||
example:
|
||||
'/api/v3/records/1/48'
|
||||
RecordsUriArray:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/RecordUri'
|
||||
|
||||
ApiResponse_RecordsUriArray:
|
||||
type: object
|
||||
properties:
|
||||
meta:
|
||||
$ref: '#/ApiResponse_meta'
|
||||
response:
|
||||
$ref: '#/RecordsUriArray'
|
||||
|
||||
|
||||
Reference in New Issue
Block a user