references/openproject
1
0
Fork 0
mirror of https://github.com/opf/openproject.git synced 2026-06-13 19:20:00 +00:00
Code Issues Packages Projects Releases Wiki Activity

[#40228] amended apispec for changes to file links

Browse Source 
- https://community.openproject.org/work_packages/40228
- added schema for work packages collection
- moved Read and Delete of file links by id out of work package context
- fixed file link schema to fit reading and creating
- fixed validation warning about exclusiveMinimum
This commit is contained in:
Eric Schubert
2022-02-21 13:57:53 +01:00
parent 817985e9aa
commit 7836eedf0c
11 changed files with 330 additions and 402 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.redocly.lint-ignore.yaml
+1 -2
View File
@@ -3,7 +3,6 @@ tmp/oas-generated.yml:
- '#/info'
operation-2xx-response:
- '#/paths/~1api~1v3~1work_packages~1{id}~1relations/get/responses'
- '#/paths/~1api~1v3~1work_packages~1{id}~1file_links~1{file_link_id}~1download/get/responses'
- '#/paths/~1api~1v3~1work_packages~1{id}~1file_links~1{file_link_id}~1open/get/responses'
- '#/paths/~1api~1v3~1file_links~1{file_link_id}~1open/get/responses'
operation-4xx-response:
- '#/paths/~1api~1v3~1work_packages~1{id}~1relations/get/responses'
docs/api/apiv3/components/schemas/file_link_model.yml
+1 -35
View File
@@ -2,9 +2,8 @@
---
type: object
required:
- id
- _type
- originData
- _links
properties:
id:
type: integer
@@ -41,16 +40,6 @@ properties:
- $ref: './work_package_model.yml'
_links:
type: object
required:
- self
- storage
- container
- creator
- delete
- downloadLocation
- staticDownloadLocation
- originOpen
- staticOriginOpen
properties:
self:
allOf:
@@ -67,7 +56,6 @@ properties:
The storage resource of the linked file.
**Resource**: Storage
readOnly: true
storageUrl:
allOf:
- $ref: './link.yml'
@@ -100,22 +88,6 @@ properties:
- description: |-
The uri to delete the file link.
**Resource**: N/A
readOnly: true
downloadLocation:
allOf:
- $ref: './link.yml'
- description: |-
The uri to download the origin file from.
**Resource**: N/A
readOnly: true
staticDownloadLocation:
allOf:
- $ref: './link.yml'
- description: |-
A static uri to download the origin filefrom the storage. Responds with a redirect.
**Resource**: N/A
readOnly: true
originOpen:
@@ -200,12 +172,6 @@ example:
delete:
href: /api/v3/work_package/17/file_links/1337
title: file link delete API
downloadLocation:
href: https://nextcloud.deathstar.rocks/index.php/dl?fileid=5503
title: file download
staticDownloadLocation:
href: /api/v3/work_package/17/file_links/1337/download
title: file link static download API
originOpen:
href: https://nextcloud.deathstar.rocks/index.php/f?fileid=5503
title: file open
docs/api/apiv3/components/schemas/project_model.yml
+1 -2
View File
@@ -5,8 +5,7 @@ properties:
id:
type: integer
description: Projects' id
minimum: 0
exclusiveMinimum: true
minimum: 1
identifier:
type: string
name:
docs/api/apiv3/components/schemas/work_package_model.yml
+263 -263
View File
@@ -2,15 +2,14 @@
---
type: object
required:
- subject
- type
- subject
- _links
properties:
id:
type: integer
description: Work package id
readOnly: true
minimum: 0
exclusiveMinimum: true
minimum: 1
lockVersion:
type: integer
description: The version of the item as used for optimistic locking
@@ -18,14 +17,15 @@ properties:
subject:
type: string
description: Work package subject
type:
_type:
type: string
description: Name of the work package's type
enum:
- WorkPackage
readOnly: true
description:
allOf:
- "$ref": "./formattable.yml"
- description: The work package description
- "$ref": "./formattable.yml"
- description: The work package description
scheduleManually:
type: boolean
description: If false (default) schedule automatically.
@@ -91,308 +91,308 @@ properties:
_links:
type: object
required:
- self
- schema
- ancestors
- attachments
- author
- children
- priority
- project
- status
- type
- self
- schema
- ancestors
- attachments
- author
- children
- priority
- project
- status
- type
properties:
addAttachment:
allOf:
- "$ref": "./link.yml"
- description: |-
Attach a file to the WP
# Conditions
**Permission**: edit work package
readOnly: true
- "$ref": "./link.yml"
- description: |-
Attach a file to the WP
# Conditions
**Permission**: edit work package
readOnly: true
addComment:
allOf:
- "$ref": "./link.yml"
- description: |-
Post comment to WP
# Conditions
**Permission**: add work package notes
readOnly: true
- "$ref": "./link.yml"
- description: |-
Post comment to WP
# Conditions
**Permission**: add work package notes
readOnly: true
addRelation:
allOf:
- "$ref": "./link.yml"
- description: |-
Adds a relation to this work package.
# Conditions
**Permission**: manage wp relations
readOnly: true
- "$ref": "./link.yml"
- description: |-
Adds a relation to this work package.
# Conditions
**Permission**: manage wp relations
readOnly: true
addWatcher:
allOf:
- "$ref": "./link.yml"
- description: |-
Add any user to WP watchers
# Conditions
**Permission**: add watcher
readOnly: true
- "$ref": "./link.yml"
- description: |-
Add any user to WP watchers
# Conditions
**Permission**: add watcher
readOnly: true
customActions:
allOf:
- "$ref": "./link.yml"
- description: Collection of predefined changes that can be applied to the
work package
readOnly: true
- "$ref": "./link.yml"
- description: Collection of predefined changes that can be applied to the
work package
readOnly: true
previewMarkup:
allOf:
- "$ref": "./link.yml"
- description: Post markup (in markdown) here to receive an HTML-rendered
response
readOnly: true
- "$ref": "./link.yml"
- description: Post markup (in markdown) here to receive an HTML-rendered
response
readOnly: true
removeWatcher:
allOf:
- "$ref": "./link.yml"
- description: |-
Remove any user from WP watchers
# Conditions
**Permission**: delete watcher
readOnly: true
- "$ref": "./link.yml"
- description: |-
Remove any user from WP watchers
# Conditions
**Permission**: delete watcher
readOnly: true
unwatch:
allOf:
- "$ref": "./link.yml"
- description: |-
Remove current user from WP watchers
# Conditions
logged in; watching
readOnly: true
- "$ref": "./link.yml"
- description: |-
Remove current user from WP watchers
# Conditions
logged in; watching
readOnly: true
update:
allOf:
- "$ref": "./link.yml"
- description: |-
Form endpoint that aids in preparing and performing edits on a WP
# Conditions
**Permission**: edit work package
readOnly: true
- "$ref": "./link.yml"
- description: |-
Form endpoint that aids in preparing and performing edits on a WP
# Conditions
**Permission**: edit work package
readOnly: true
updateImmediately:
allOf:
- "$ref": "./link.yml"
- description: |-
Directly perform edits on a work package
# Conditions
**Permission**: edit work package
readOnly: true
- "$ref": "./link.yml"
- description: |-
Directly perform edits on a work package
# Conditions
**Permission**: edit work package
readOnly: true
watch:
allOf:
- "$ref": "./link.yml"
- description: |-
Add current user to WP watchers
# Conditions
logged in; not watching
readOnly: true
- "$ref": "./link.yml"
- description: |-
Add current user to WP watchers
# Conditions
logged in; not watching
readOnly: true
self:
allOf:
- "$ref": "./link.yml"
- description: |-
This work package
**Resource**: WorkPackage
readOnly: true
- "$ref": "./link.yml"
- description: |-
This work package
**Resource**: WorkPackage
readOnly: true
schema:
allOf:
- "$ref": "./link.yml"
- description: |-
The schema of this work package
**Resource**: Schema
readOnly: true
- "$ref": "./link.yml"
- description: |-
The schema of this work package
**Resource**: Schema
readOnly: true
ancestors:
allOf:
- "$ref": "./link.yml"
- description: |-
Array of all visible ancestors of the work package, with the root node being the first element
**Resource**: Collection
# Conditions
**Permission** view work packages
readOnly: true
- "$ref": "./link.yml"
- description: |-
Array of all visible ancestors of the work package, with the root node being the first element
**Resource**: Collection
# Conditions
**Permission** view work packages
readOnly: true
attachments:
allOf:
- "$ref": "./link.yml"
- description: |-
The files attached to this work package
**Resource**: Collection
- "$ref": "./link.yml"
- description: |-
The files attached to this work package
**Resource**: Collection
author:
allOf:
- "$ref": "./link.yml"
- description: |-
The person that created the work package
**Resource**: User
readOnly: true
- "$ref": "./link.yml"
- description: |-
The person that created the work package
**Resource**: User
readOnly: true
assignee:
allOf:
- "$ref": "./link.yml"
- description: |-
The person that is intended to work on the work package
**Resource**: User
- "$ref": "./link.yml"
- description: |-
The person that is intended to work on the work package
**Resource**: User
availableWatchers:
allOf:
- "$ref": "./link.yml"
- description: |-
All users that can be added to the work package as watchers.
**Resource**: User
# Conditions
**Permission** add work package watchers
readOnly: true
- "$ref": "./link.yml"
- description: |-
All users that can be added to the work package as watchers.
**Resource**: User
# Conditions
**Permission** add work package watchers
readOnly: true
budget:
allOf:
- "$ref": "./link.yml"
- description: |-
The budget this work package is associated to
**Resource**: Budget
# Conditions
**Permission** view cost objects
- "$ref": "./link.yml"
- description: |-
The budget this work package is associated to
**Resource**: Budget
# Conditions
**Permission** view cost objects
category:
allOf:
- "$ref": "./link.yml"
- description: |-
The category of the work package
**Resource**: Category
- "$ref": "./link.yml"
- description: |-
The category of the work package
**Resource**: Category
children:
allOf:
- "$ref": "./link.yml"
- description: |-
Array of all visible children of the work package
**Resource**: Collection
# Conditions
**Permission** view work packages
readOnly: true
- "$ref": "./link.yml"
- description: |-
Array of all visible children of the work package
**Resource**: Collection
# Conditions
**Permission** view work packages
readOnly: true
parent:
allOf:
- "$ref": "./link.yml"
- description: |-
Parent work package
**Resource**: WorkPackage
- "$ref": "./link.yml"
- description: |-
Parent work package
**Resource**: WorkPackage
priority:
allOf:
- "$ref": "./link.yml"
- description: |-
The priority of the work package
**Resource**: Priority
- "$ref": "./link.yml"
- description: |-
The priority of the work package
**Resource**: Priority
project:
allOf:
- "$ref": "./link.yml"
- description: |-
The project to which the work package belongs
**Resource**: Project
- "$ref": "./link.yml"
- description: |-
The project to which the work package belongs
**Resource**: Project
responsible:
allOf:
- "$ref": "./link.yml"
- description: |-
The person that is responsible for the overall outcome
**Resource**: User
- "$ref": "./link.yml"
- description: |-
The person that is responsible for the overall outcome
**Resource**: User
relations:
allOf:
- "$ref": "./link.yml"
- description: |-
Relations this work package is involved in
**Resource**: Relation
# Conditions
**Permission** view work packages
readOnly: true
- "$ref": "./link.yml"
- description: |-
Relations this work package is involved in
**Resource**: Relation
# Conditions
**Permission** view work packages
readOnly: true
revisions:
allOf:
- "$ref": "./link.yml"
- description: |-
Revisions that are referencing the work package
**Resource**: Revision
# Conditions
**Permission** view changesets
readOnly: true
- "$ref": "./link.yml"
- description: |-
Revisions that are referencing the work package
**Resource**: Revision
# Conditions
**Permission** view changesets
readOnly: true
status:
allOf:
- "$ref": "./link.yml"
- description: |-
The current status of the work package
**Resource**: Status
- "$ref": "./link.yml"
- description: |-
The current status of the work package
**Resource**: Status
timeEntries:
allOf:
- "$ref": "./link.yml"
- description: |-
All time entries logged on the work package. Please note that this is a link to an HTML resource for now and as such, the link is subject to change.
**Resource**: N/A
# Conditions
**Permission** view time entries
readOnly: true
- "$ref": "./link.yml"
- description: |-
All time entries logged on the work package. Please note that this is a link to an HTML resource for now and as such, the link is subject to change.
**Resource**: N/A
# Conditions
**Permission** view time entries
readOnly: true
type:
allOf:
- "$ref": "./link.yml"
- description: |-
The type of the work package
**Resource**: Type
- "$ref": "./link.yml"
- description: |-
The type of the work package
**Resource**: Type
version:
allOf:
- "$ref": "./link.yml"
- description: |-
The version associated to the work package
**Resource**: Version
- "$ref": "./link.yml"
- description: |-
The version associated to the work package
**Resource**: Version
watchers:
allOf:
- "$ref": "./link.yml"
- description: |-
All users that are currently watching this work package
**Resource**: Collection
# Conditions
**Permission** view work package watchers
readOnly: true
- "$ref": "./link.yml"
- description: |-
All users that are currently watching this work package
**Resource**: Collection
# Conditions
**Permission** view work package watchers
readOnly: true
example:
_type: WorkPackage
_links:
@@ -426,12 +426,12 @@ example:
href: "/api/v3/users/1"
title: OpenProject Admin - admin
customActions:
- href: "/api/v3/work_packages/1528/custom_actions/153/execute"
method: post
title: Reset
- href: "/api/v3/work_packages/1528/custom_actions/94/execute"
method: post
title: Forward to accounting
- href: "/api/v3/work_packages/1528/custom_actions/153/execute"
method: post
title: Reset
- href: "/api/v3/work_packages/1528/custom_actions/94/execute"
method: post
title: Forward to accounting
responsible:
href: "/api/v3/users/23"
title: Laron Leuschke - Alaina5788
@@ -496,15 +496,15 @@ example:
href: "/api/v3/categories/1298"
title: eligend isi
children:
- href: "/api/v3/work_packages/1529"
title: Write API documentation
- href: "/api/v3/work_packages/1529"
title: Write API documentation
ancestors:
- href: "/api/v3/work_packages/1290"
title: Root node of hierarchy
- href: "/api/v3/work_packages/1291"
title: Intermediate node of hierarchy
- href: "/api/v3/work_packages/1298"
title: nisi eligendi officiis eos delectus quis voluptas dolores
- href: "/api/v3/work_packages/1290"
title: Root node of hierarchy
- href: "/api/v3/work_packages/1291"
title: Intermediate node of hierarchy
- href: "/api/v3/work_packages/1298"
title: nisi eligendi officiis eos delectus quis voluptas dolores
timeEntries:
href: "/work_packages/1528/time_entries"
type: text/html
@@ -520,10 +520,10 @@ example:
raw: Develop super cool OpenProject API.
html: "<p>Develop super cool OpenProject API.</p>"
scheduleManually: false
startDate:
dueDate:
derivedStartDate:
derivedDueDate:
startDate:
dueDate:
derivedStartDate:
derivedDueDate:
estimatedTime: PT2H
derivedEstimatedTime: PT10H
percentageDone: 0
docs/api/apiv3/components/schemas/work_packages_model.yml
+42 -12
View File
@@ -1,5 +1,35 @@
# Schema: Work_PackagesModel
---
allOf:
- "$ref": "./collection_model.yml"
- type: object
required:
- _links
- _embedded
properties:
_links:
type: object
required:
- self
properties:
self:
allOf:
- "$ref": "./link.yml"
- description: |-
The watcher list
**Resource**: WatchersModel
readOnly: true
_embedded:
type: object
required:
- elements
properties:
elements:
type: array
items:
$ref: './work_package_model.yml'
type: object
example:
_links:
@@ -10,15 +40,15 @@ example:
_type: Collection
_embedded:
elements:
- _type: WorkPackage
_links:
self:
href: "/api/v3/work_packages/1"
id: 1
subject: Skipped other properties for brevity
- _type: WorkPackage
_links:
self:
href: "/api/v3/work_packages/2"
id: 2
subject: Skipped other properties for brevity
- _hint: Work package resource shortened for brevity
_type: WorkPackage
_links:
self:
href: "/api/v3/work_packages/1"
id: 1
- _hint: Work package resource shortened for brevity
_type: WorkPackage
_links:
self:
href: "/api/v3/work_packages/2"
id: 2
docs/api/apiv3/openapi-spec.yml
+4 -14
View File
@@ -182,6 +182,10 @@ paths:
"$ref": "./paths/example_schema.yml"
"/api/v3/examples":
"$ref": "./paths/examples.yml"
"/api/v3/file_links/{id}":
"$ref": "./paths/file_link.yml"
"/api/v3/file_links/{id}/open":
"$ref": "./paths/file_link_open.yml"
"/api/v3/grids":
"$ref": "./paths/grids.yml"
"/api/v3/grids/form":
@@ -396,12 +400,6 @@ paths:
"$ref": "./paths/work_package_available_watchers.yml"
"/api/v3/work_packages/{id}/file_links":
"$ref": "./paths/work_package_file_links.yml"
"/api/v3/work_packages/{id}/file_links/{file_link_id}":
"$ref": "./paths/work_package_file_link.yml"
"/api/v3/work_packages/{id}/file_links/{file_link_id}/download":
"$ref": "./paths/work_package_file_link_download.yml"
"/api/v3/work_packages/{id}/file_links/{file_link_id}/open":
"$ref": "./paths/work_package_file_link_open.yml"
"/api/v3/work_packages/{id}/form":
"$ref": "./paths/work_package_form.yml"
"/api/v3/work_packages/{id}/revisions":
@@ -751,16 +749,8 @@ components:
"$ref": "./components/schemas/wiki_page_model.yml"
Work_PackageModel:
"$ref": "./components/schemas/work_package_model.yml"
Work_Package_Create_Form:
"$ref": "./components/schemas/work_package_create_form.yml"
Work_Package_Create_Form_For_Project:
"$ref": "./components/schemas/work_package_create_form_for_project.yml"
Work_Package_Edit_Form:
"$ref": "./components/schemas/work_package_edit_form.yml"
Work_Package_Relation_FormModel:
"$ref": "./components/schemas/work_package_relation_form_model.yml"
Work_Package_Schema:
"$ref": "./components/schemas/work_package_schema.yml"
Work_Package_SchemasModel:
"$ref": "./components/schemas/work_package_schemas_model.yml"
Work_Package_activitiesModel:
docs/api/apiv3/paths/work_package_file_link.yml → docs/api/apiv3/paths/file_link.yml
+1 -15
View File
@@ -1,4 +1,4 @@
# /api/v3/work_packages/{id}/file_links/{file_link_id}
# /api/v3/file_links/{id}
---
get:
summary: Gets a file link.
@@ -10,13 +10,6 @@ get:
Gets a single file link resource of a work package.
parameters:
- name: id
description: Work package id
in: path
required: true
schema:
type: integer
example: 1337
- name: file_link_id
description: File link id
in: path
required: true
@@ -56,13 +49,6 @@ delete:
The request contains only the file link identifier as a path parameter. No request body is needed.
parameters:
- name: id
description: Work package id
in: path
required: true
schema:
type: integer
example: 1337
- name: file_link_id
description: File link id
in: path
required: true
docs/api/apiv3/paths/work_package_file_link_open.yml → docs/api/apiv3/paths/file_link_open.yml
+1 -8
View File
@@ -1,4 +1,4 @@
# /api/v3/work_packages/{id}/file_links/{file_link_id}/open
# /api/v3/file_links/{id}/open
---
get:
summary: Creates an opening uri of the linked file.
@@ -11,13 +11,6 @@ get:
always is located on the origin storage itself.
parameters:
- name: id
description: Work package id
in: path
required: true
schema:
type: integer
example: 1337
- name: file_link_id
description: File link id
in: path
required: true
docs/api/apiv3/paths/work_package_file_link_download.yml
-49
View File
@@ -1,49 +0,0 @@
# /api/v3/work_packages/{id}/file_links/{file_link_id}/download
---
get:
summary: Creates a download uri of the linked file.
operationId: Work_Package_File_Link_Download
tags:
- Work Packages
- File links
description: |-
Creates a download uri of the origin file linked by the given file link. This uri depends on the storage type and
always is located on the origin storage itself.
parameters:
- name: id
description: Work package id
in: path
required: true
schema:
type: integer
example: 1337
- name: file_link_id
description: File link id
in: path
required: true
schema:
type: integer
example: 42
responses:
'303':
headers:
Location:
schema:
type: string
format: uri
description: |-
Returned if the request was successful. In the `Location` header is the uri where the client can download the
origin file from the storage.
'404':
content:
application/hal+json:
schema:
$ref: "../components/schemas/error_response.yml"
example:
_type: Error
errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
message: The requested resource could not be found.
description: |-
Returned if the work package does not exist or the client does not have sufficient permissions to see it.
**Required permission:** view work package, view file links
docs/api/apiv3/paths/work_package_file_links.yml
+14 -2
View File
@@ -1,4 +1,4 @@
# /api/v3/work_packages/{id}/file_links/
# /api/v3/work_packages/{id}/file_links
---
post:
summary: Creates file links.
@@ -69,7 +69,7 @@ post:
_links:
storageUrl:
href: https://nextcloud.deathstar.rocks/
responses:
'201':
description: Created
@@ -140,6 +140,18 @@ post:
Returned if the work package does not exist or the client does not have sufficient permissions to see it.
**Required permission:** view work package, view file links
'422':
content:
application/hal+json:
schema:
$ref: "../components/schemas/error_response.yml"
example:
_type: Error
errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
message: The request was invalid. File Link logo.png - Storage was invalid.
description: |-
Occurs if the request body was correctly formatted, but some properties lead to errors in the validation
process. This happens e.g. if the provided storage url is not available on the server.
get:
summary: Gets all file links of a work package
operationId: Work_Package_Get_File_Links
docs/api/apiv3/paths/work_packages.yml
+2
View File
@@ -47,6 +47,8 @@ get:
- group
- id
- includes
- linkable_to_storage_id
- linkable_to_storage_url
- manual_sort
- milestone
- only_subproject