From 1d91aa181e1dfe00048ec04cb901f8d97c7618f1 Mon Sep 17 00:00:00 2001 From: Eric Schubert Date: Mon, 26 Aug 2024 13:53:02 +0200 Subject: [PATCH 1/3] [#40945] updated work package form API specs - https://community.openproject.org/work_packages/40945 - added model for work package form - added model for work package schema - updated work package write and patch model - all changes are considered incomplete, as the whole content around schemas is not yet covered 100% inside the API documentation --- .../schemas/work_package_form_model.yml | 54 ++++++ .../schemas/work_package_patch_model.yml | 181 +----------------- .../schemas/work_package_schema_model.yml | 92 +++++++++ .../schemas/work_package_schemas_model.yml | 20 -- .../schemas/work_package_write_model.yml | 115 +++++++++++ docs/api/apiv3/openapi-spec.yml | 14 +- .../paths/project_work_packages_form.yml | 39 ++-- docs/api/apiv3/paths/work_package_form.yml | 67 ++----- .../api/apiv3/paths/work_packages_schemas.yml | 62 +++--- docs/api/apiv3/tags/users.yml | 30 +-- 10 files changed, 370 insertions(+), 304 deletions(-) create mode 100644 docs/api/apiv3/components/schemas/work_package_form_model.yml create mode 100644 docs/api/apiv3/components/schemas/work_package_schema_model.yml delete mode 100644 docs/api/apiv3/components/schemas/work_package_schemas_model.yml create mode 100644 docs/api/apiv3/components/schemas/work_package_write_model.yml diff --git a/docs/api/apiv3/components/schemas/work_package_form_model.yml b/docs/api/apiv3/components/schemas/work_package_form_model.yml new file mode 100644 index 000000000000..16b7bfb11ce2 --- /dev/null +++ b/docs/api/apiv3/components/schemas/work_package_form_model.yml @@ -0,0 +1,54 @@ +# Schema: WorkPackageFormModel +--- +type: object +description: |- + The work package creation form. This object is returned, whenever a work package form endpoint is called. It contains + an allowed payload definition, the full schema and any validation errors on the current request body. +properties: + _type: + type: string + enum: + - Form + _embedded: + type: object + properties: + payload: + $ref: './work_package_write_model.yml' + schema: + $ref: './work_package_schema_model.yml' + validationErrors: + type: array + items: + type: object + description: |- + A list of validation errors. This list is empty, if the request body is valid. + _links: + type: object + properties: + self: + allOf: + - $ref: './link.yml' + - description: |- + This form endpoint + + **Resource** : Form + validate: + allOf: + - $ref: './link.yml' + - description: |- + The endpoint for validating the request bodies. Often referring to this very form endpoint. + previewMarkup: + allOf: + - $ref: './link.yml' + - description: |- + Renders a markup preview for the work package form. + customFields: + allOf: + - $ref: './link.yml' + - description: |- + Link to the HTML page for the custom field definitions. + configureForm: + allOf: + - $ref: './link.yml' + - description: |- + Link to the HTML page for the form configuration. diff --git a/docs/api/apiv3/components/schemas/work_package_patch_model.yml b/docs/api/apiv3/components/schemas/work_package_patch_model.yml index fc5aae1d604f..9c9690ac3edc 100644 --- a/docs/api/apiv3/components/schemas/work_package_patch_model.yml +++ b/docs/api/apiv3/components/schemas/work_package_patch_model.yml @@ -1,176 +1,11 @@ # Schema: WorkPackagePatchModel --- -type: object -required: - - lockVersion -properties: - lockVersion: - type: integer - description: The version of the item as used for optimistic locking - subject: - type: string - description: Work package subject - description: - allOf: - - $ref: "./formattable.yml" - - description: The work package description - scheduleManually: - type: boolean - description: If false (default) schedule automatically. - startDate: - type: string - format: date - description: Scheduled beginning of a work package - dueDate: - type: string - format: date - description: Scheduled end of a work package - date: - type: string - format: date - description: Date on which a milestone is achieved - estimatedTime: - type: string - format: duration - description: Time a work package likely needs to be completed excluding its descendants - ignoreNonWorkingDays: - type: boolean - description: |- - **(NOT IMPLEMENTED)** When scheduling, whether or not to ignore the non working days being defined. - A work package with the flag set to true will be allowed to be scheduled to a non working day. - readOnly: true - spentTime: - type: string - format: duration - description: |- - The time booked for this work package by users working on it - - # Conditions - - **Permission** view time entries - readOnly: true - percentageDone: - type: integer - description: Amount of total completion for a work package - maximum: 100 - createdAt: - type: string - format: date-time - description: Time of creation - readOnly: true - updatedAt: - type: string - format: date-time - description: Time of the most recent change to the work package - readOnly: true - _links: - type: object +allOf: + - $ref: './work_package_write_model.yml' + - type: object + required: + - lockVersion properties: - assignee: - allOf: - - $ref: "./link.yml" - - description: |- - The person that is intended to work on the work package - - **Resource**: User - budget: - allOf: - - $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 - parent: - allOf: - - $ref: "./link.yml" - - description: |- - Parent work package - - **Resource**: WorkPackage - priority: - allOf: - - $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 - responsible: - allOf: - - $ref: "./link.yml" - - description: |- - The person that is responsible for the overall outcome - - **Resource**: User - status: - allOf: - - $ref: "./link.yml" - - description: |- - The current status of the work package - - **Resource**: Status - type: - allOf: - - $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 - -examples: - - subject: Upgrade hangar 25 - lockVersion: 0 - description: - format: markdown - raw: we need more place for new TIE Advanced - html: "

we need more place for new TIE Advanced

" - scheduleManually: false - _links: - responsible: - href: "/api/v3/users/23" - title: Palpatine - assignee: - href: "/api/v3/users/33" - title: Darth Vader - priority: - href: "/api/v3/priorities/2" - title: Normal - project: - href: "/api/v3/projects/1" - title: Galactic Conquest - status: - href: "/api/v3/statuses/1" - title: New - type: - href: "/api/v3/types/11" - title: DeathStarUpgrades - version: - href: "/api/v3/versions/1" - title: Version 1 - parent: - href: "/api/v3/work_packages/1298" - title: ct'hulhu f'tagn + lockVersion: + type: integer + description: The version of the item as used for optimistic locking diff --git a/docs/api/apiv3/components/schemas/work_package_schema_model.yml b/docs/api/apiv3/components/schemas/work_package_schema_model.yml new file mode 100644 index 000000000000..c900a77b087a --- /dev/null +++ b/docs/api/apiv3/components/schemas/work_package_schema_model.yml @@ -0,0 +1,92 @@ +# Schema: WorkPackageSchemaModel +--- +type: object +description: |- + A schema for a work package. This schema defines the attributes of a work package. + + TODO: Incomplete, needs to be updated with the real behaviour of schemas (when does which attribute appear?). +properties: + _type: + type: string + enum: + - Schema + _dependencies: + type: array + items: + type: string + description: TBD + _attributeGroups: + type: array + items: + type: object + description: TBD (WorkPackageFormAttributeGroup) + lockVersion: + $ref: './schema_property_model.yml' + id: + $ref: './schema_property_model.yml' + subject: + $ref: './schema_property_model.yml' + description: + $ref: './schema_property_model.yml' + duration: + $ref: './schema_property_model.yml' + scheduleManually: + $ref: './schema_property_model.yml' + ignoreNonWorkingDays: + $ref: './schema_property_model.yml' + startDate: + $ref: './schema_property_model.yml' + dueDate: + $ref: './schema_property_model.yml' + derivedStartDate: + $ref: './schema_property_model.yml' + derivedDueDate: + $ref: './schema_property_model.yml' + estimatedTime: + $ref: './schema_property_model.yml' + derivedEstimatedTime: + $ref: './schema_property_model.yml' + remainingTime: + $ref: './schema_property_model.yml' + derivedRemainingTime: + $ref: './schema_property_model.yml' + percentageDone: + $ref: './schema_property_model.yml' + derivedPercentageDone: + $ref: './schema_property_model.yml' + readonly: + $ref: './schema_property_model.yml' + createdAt: + $ref: './schema_property_model.yml' + updatedAt: + $ref: './schema_property_model.yml' + author: + $ref: './schema_property_model.yml' + project: + $ref: './schema_property_model.yml' + parent: + $ref: './schema_property_model.yml' + assignee: + $ref: './schema_property_model.yml' + responsible: + $ref: './schema_property_model.yml' + type: + $ref: './schema_property_model.yml' + status: + $ref: './schema_property_model.yml' + category: + $ref: './schema_property_model.yml' + version: + $ref: './schema_property_model.yml' + priority: + $ref: './schema_property_model.yml' + _links: + type: object + properties: + self: + allOf: + - $ref: './link.yml' + - description: |- + This work package schema + + **Resource**: Schema diff --git a/docs/api/apiv3/components/schemas/work_package_schemas_model.yml b/docs/api/apiv3/components/schemas/work_package_schemas_model.yml deleted file mode 100644 index 4a7dd065c0a8..000000000000 --- a/docs/api/apiv3/components/schemas/work_package_schemas_model.yml +++ /dev/null @@ -1,20 +0,0 @@ -# Schema: Work_Package_SchemasModel ---- -type: object -example: - _links: - self: - href: "/api/v3/work_packages/schemas" - total: 5 - count: 2 - _type: Collection - _embedded: - elements: - - _type: Schema... - _links: - self: - href: "/api/v3/work_packages/schemas/13-1" - - _type: Schema... - _links: - self: - href: "/api/v3/work_packages/schemas/7-6" diff --git a/docs/api/apiv3/components/schemas/work_package_write_model.yml b/docs/api/apiv3/components/schemas/work_package_write_model.yml new file mode 100644 index 000000000000..990dbb4ff9de --- /dev/null +++ b/docs/api/apiv3/components/schemas/work_package_write_model.yml @@ -0,0 +1,115 @@ +# Schema: WorkPackageWriteModel +--- +type: object +properties: + subject: + type: string + description: Work package subject + description: + allOf: + - $ref: './formattable.yml' + - description: The work package description + scheduleManually: + type: boolean + description: If false (default) schedule automatically. + startDate: + type: + - 'string' + - 'null' + format: date + description: Scheduled beginning of a work package + dueDate: + type: + - 'string' + - 'null' + format: date + description: Scheduled end of a work package + estimatedTime: + type: + - 'string' + - 'null' + format: duration + description: Time a work package likely needs to be completed excluding its descendants + duration: + type: + - 'string' + - 'null' + format: duration + description: |- + The amount of time in hours the work package needs to be completed. This value must be bigger or equal to `P1D`, + and any the value will get floored to the nearest day. + + The duration has no effect, unless either a start date or a due date is set. + + Not available for milestone type of work packages. + ignoreNonWorkingDays: + type: boolean + description: |- + When scheduling, whether or not to ignore the non working days being defined. + A work package with the flag set to true will be allowed to be scheduled to a non working day. + _links: + type: object + properties: + category: + allOf: + - $ref: './link.yml' + - description: |- + The category of the work package + + **Resource**: Category + type: + allOf: + - $ref: './link.yml' + - description: |- + The type of the work package + + **Resource**: Type + priority: + allOf: + - $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 + status: + allOf: + - $ref: './link.yml' + - description: |- + The current status of the work package + + **Resource**: Status + responsible: + allOf: + - $ref: './link.yml' + - description: |- + The person that is responsible for the overall outcome + + **Resource**: User + assignee: + allOf: + - $ref: './link.yml' + - description: |- + The person that is intended to work on the work package + + **Resource**: User + version: + allOf: + - $ref: './link.yml' + - description: |- + The version associated to the work package + + **Resource**: Version + parent: + allOf: + - $ref: './link.yml' + - description: |- + Parent work package + + **Resource**: WorkPackage diff --git a/docs/api/apiv3/openapi-spec.yml b/docs/api/apiv3/openapi-spec.yml index f03d67d66aec..e558237e6b90 100644 --- a/docs/api/apiv3/openapi-spec.yml +++ b/docs/api/apiv3/openapi-spec.yml @@ -867,16 +867,20 @@ components: "$ref": "./components/schemas/week_day_write_model.yml" Wiki_PageModel: "$ref": "./components/schemas/wiki_page_model.yml" - Work_PackageModel: + WorkPackageModel: "$ref": "./components/schemas/work_package_model.yml" - Work_Package_SchemasModel: - "$ref": "./components/schemas/work_package_schemas_model.yml" + WorkPackageFormModel: + "$ref": "./components/schemas/work_package_form_model.yml" + WorkPackagePatchModel: + "$ref": "./components/schemas/work_package_patch_model.yml" + WorkPackageSchemaModel: + "$ref": "./components/schemas/work_package_schema_model.yml" + WorkPackageWriteModel: + "$ref": "./components/schemas/work_package_write_model.yml" Work_Package_activitiesModel: "$ref": "./components/schemas/work_package_activities_model.yml" Work_PackagesModel: "$ref": "./components/schemas/work_packages_model.yml" - WorkPackagePatchModel: - "$ref": "./components/schemas/work_package_patch_model.yml" securitySchemes: BasicAuth: type: http diff --git a/docs/api/apiv3/paths/project_work_packages_form.yml b/docs/api/apiv3/paths/project_work_packages_form.yml index 57c6280d48e2..86321426ba93 100644 --- a/docs/api/apiv3/paths/project_work_packages_form.yml +++ b/docs/api/apiv3/paths/project_work_packages_form.yml @@ -1,20 +1,33 @@ # /api/v3/projects/{id}/work_packages/form --- post: + summary: Work Package Create Form For Project + operationId: Work_Package_Create_Form_For_Project + tags: + - Work Packages + description: |- + This endpoint allows you to validation a new work package creation body in a specific project. It works similarly + to the `/api/v3/work_packages/form` endpoint, but already specifies the work package's project in the path, so that + it does not have to be defined in the request body. parameters: - - description: ID of the project in which the work package will be created - example: '1' - in: path - name: id - required: true - schema: - type: integer + - name: id + description: ID of the project in which the work package will be created + in: path + required: true + schema: + type: integer + example: '1' + requestBody: + content: + application/json: + schema: + $ref: '../components/schemas/work_package_write_model.yml' responses: '200': description: OK - headers: {} - tags: - - Work Packages - description: '' - operationId: Work_Package_Create_Form_For_Project - summary: Work Package Create Form For Project + content: + application/json: + schema: + $ref: '../components/schemas/work_package_form_model.yml' + '415': + $ref: '../components/responses/unsupported_media_type.yml' diff --git a/docs/api/apiv3/paths/work_package_form.yml b/docs/api/apiv3/paths/work_package_form.yml index c63fadd615d0..0e0d6fad2995 100644 --- a/docs/api/apiv3/paths/work_package_form.yml +++ b/docs/api/apiv3/paths/work_package_form.yml @@ -6,63 +6,36 @@ post: tags: - Work Packages description: |- - When calling this endpoint, the client provides a single object containing the properties and links to be edited, in the body. + When calling this endpoint, the client provides a single object containing the properties and links to be + created, in the body. The input is validated and a schema response is returned. If the validation errors of the + response is empty, the same payload can be used to create a work package. - Note that it is only allowed to provide properties or links supporting the write operation. + Only the properties of the work package write model are allowed to set on a work package on creation. - When setting start date, finish date, and duration together, their correctness will be checked and a 422 error will be returned if one value does not match with the two others. You can make the server compute a value: set only two values in the request and the third one will be computed and returned in the response. For instance, when sending `{ "startDate": "2022-08-23", duration: "P2D" }`, the response will include `{ "dueDate": "2022-08-24" }`. + When setting start date, finish date, and duration together, their correctness will be checked and a validation + error will be returned if one value does not match with the two others. You can make the server compute a value: + set only two values in the request and the third one will be computed and returned in the response. For instance, + when sending `{ "startDate": "2022-08-23", duration: "P2D" }`, the response will + include `{ "dueDate": "2022-08-24" }`. requestBody: content: application/json: schema: - "$ref": "../components/schemas/work_package_model.yml" + $ref: '../components/schemas/work_package_write_model.yml' parameters: - - description: ID of the work package being modified - example: '1' - in: path - name: id - required: true - schema: - type: integer + - name: id + description: ID of the work package being modified + in: path + required: true + schema: + type: integer + example: '1' responses: '200': description: OK - headers: {} - '403': content: - application/hal+json: + application/json: schema: - $ref: "../components/schemas/error_response.yml" - examples: - response: - value: - _type: Error - errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission - message: You are not allowed to edit the specified work package. - description: |- - Returned if the client does not have sufficient permissions. - - **Required permission:** edit work package, assign version, change work package status, manage subtasks or move work package - - *Note that you will only receive this error, if you are at least allowed to see the corresponding work package.* - headers: {} - '404': - content: - application/hal+json: - schema: - $ref: "../components/schemas/error_response.yml" - examples: - response: - value: - _type: Error - errorIdentifier: urn:openproject-org:api:v3:errors:NotFound - message: The specified work package does not exist. - 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 - headers: {} - '406': - $ref: "../components/responses/missing_content_type.yml" + $ref: '../components/schemas/work_package_form_model.yml' '415': - $ref: "../components/responses/unsupported_media_type.yml" + $ref: '../components/responses/unsupported_media_type.yml' diff --git a/docs/api/apiv3/paths/work_packages_schemas.yml b/docs/api/apiv3/paths/work_packages_schemas.yml index 623071ebddd1..994b8d003542 100644 --- a/docs/api/apiv3/paths/work_packages_schemas.yml +++ b/docs/api/apiv3/paths/work_packages_schemas.yml @@ -1,22 +1,31 @@ # /api/v3/work_packages/schemas/ --- get: + summary: List Work Package Schemas + operationId: list_work_package_schemas + tags: + - Work Packages + description: |- + List all work package schemas that match the given filters. This endpoint does not return a successful response, + if no filter is given. parameters: - - description: |- - JSON specifying filter conditions. - Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Currently supported filters are: - - + id: The schema's id - - Schema id has the form `project_id-work_package_type_id`. - example: '[{ "id": { "operator": "=", "values": ["12-1", "14-2"] } }]' - in: query - name: filters - required: true - schema: - type: string + - name: filters + description: |- + JSON specifying filter conditions. + Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) + endpoint. Currently supported filters are: + + + id: The schema's id + + Schema id has the form `project_id-work_package_type_id`. + in: query + required: true + schema: + type: string + example: '[{ "id": { "operator": "=", "values": ["12-1", "14-2"] } }]' responses: '200': + description: OK content: application/hal+json: examples: @@ -24,24 +33,20 @@ get: value: _embedded: elements: - - _links: - self: - href: "/api/v3/work_packages/schemas/13-1" - _type: Schema... - - _links: - self: - href: "/api/v3/work_packages/schemas/7-6" - _type: Schema... + - _links: + self: + href: "/api/v3/work_packages/schemas/13-1" + _type: Schema... + - _links: + self: + href: "/api/v3/work_packages/schemas/7-6" + _type: Schema... _links: self: href: "/api/v3/work_packages/schemas" _type: Collection count: 2 total: 5 - schema: - "$ref": "../components/schemas/work_package_schemas_model.yml" - description: OK - headers: {} '400': $ref: "../components/responses/invalid_request_body.yml" '403': @@ -59,9 +64,4 @@ get: Returned if the client does not have sufficient permissions. **Required permission:** View work packages in any project. - headers: {} - tags: - - Work Packages - description: List work package schemas. - operationId: List_Work_Package_Schemas - summary: List Work Package Schemas + headers: { } diff --git a/docs/api/apiv3/tags/users.yml b/docs/api/apiv3/tags/users.yml index 9a1eabdcfc82..f047b64d03c6 100644 --- a/docs/api/apiv3/tags/users.yml +++ b/docs/api/apiv3/tags/users.yml @@ -1,4 +1,5 @@ --- +name: Users description: |- ## Actions @@ -7,37 +8,37 @@ description: |- | lock | Restrict the user from logging in and performing any actions | not locked; **Permission**: Administrator | | show | Link to the OpenProject user page (HTML) | | | unlock | Allow a locked user to login and act again | locked; **Permission**: Administrator | - | updateImmediately | Updates the user's attributes. | **Permission**: Administrator, manage_user global permission | + | updateImmediately | Updates the user's attributes. | **Permission**: Administrator, manage_user global permission | | delete | Permanently remove a user from the instance | **Permission**: Administrator, self-delete | ## Linked Properties | Link | Description | Type | Constraints | Supported operations | Condition | - |:-----------:|-------------------------------------------------------------- | ------------- | --------------------- | -------------------- | ----------------------------------------- | + |:-----------:|--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | --------------------- | -------------------- | ----------------------------------------- | | self | This user | User | not null | READ | | - | auth_source | Link to the user's auth source (endpoint not yet implemented) | LdapAuthSource | | READ / WRITE | **Permission**: Administrator | + | auth_source | Link to the user's auth source (endpoint not yet implemented) | LdapAuthSource | | READ / WRITE | **Permission**: Administrator | | members | Link to collection of all the user's memberships. The list will only include the memberships in projects in which the requesting user has the necessary permissions. | MemberCollection | | READ | **Permission**: view members or manage members in any project | Depending on custom fields defined for users, additional links might exist. ## Local Properties - | Property | Description | Type | Constraints | Supported operations | Condition | - | :----------: | --------------------------------------------------------- | -------- | ---------------------------------------------------- | -------------------- | ----------------------------------------------------------- | - | id | User's id | Integer | x > 0 | READ | | + | Property | Description | Type | Constraints | Supported operations | Condition | + | :----------: | --------------------------------------------------------- | -------- | ---------------------------------------------------- | -------------------- | ----------------------------------------------------------- | + | id | User's id | Integer | x > 0 | READ | | | login | User's login name | String | unique, 256 max length | READ / WRITE | **Permission**: Administrator, manage_user global permission | | firstName | User's first name | String | 30 max length | READ / WRITE | **Permission**: Administrator, manage_user global permission | | lastName | User's last name | String | 30 max length | READ / WRITE | **Permission**: Administrator, manage_user global permission | - | name | User's full name, formatting depends on instance settings | String | | READ | | + | name | User's full name, formatting depends on instance settings | String | | READ | | | email | User's email address | String | unique, 60 max length | READ / WRITE | E-Mail address not hidden, **Permission**: Administrator, manage_user global permission | - | admin | Flag indicating whether or not the user is an admin | Boolean | in: [true, false] | READ / WRITE | **Permission**: Administrator | - | avatar | URL to user's avatar | Url | | READ | | - | status | The current activation status of the user (see below) | String | in: ["active", "registered", "locked", "invited"] | READ | | + | admin | Flag indicating whether or not the user is an admin | Boolean | in: [true, false] | READ / WRITE | **Permission**: Administrator | + | avatar | URL to user's avatar | Url | | READ | | + | status | The current activation status of the user (see below) | String | in: ["active", "registered", "locked", "invited"] | READ | | | language | User's language | String | ISO 639-1 | READ / WRITE | **Permission**: Administrator, manage_user global permission | - | password | User's password for the default password authentication | String | | WRITE | **Permission**: Administrator | - | identity_url | User's identity_url for OmniAuth authentication | String | | READ / WRITE | **Permission**: Administrator | - | createdAt | Time of creation | DateTime | | READ | | - | updatedAt | Time of the most recent change to the user | DateTime | | READ | | + | password | User's password for the default password authentication | String | | WRITE | **Permission**: Administrator | + | identity_url | User's identity_url for OmniAuth authentication | String | | READ / WRITE | **Permission**: Administrator | + | createdAt | Time of creation | DateTime | | READ | | + | updatedAt | Time of the most recent change to the user | DateTime | | READ | | Depending on custom fields defined for users, additional properties might exist. @@ -65,4 +66,3 @@ description: |- users except for admins or the user themselves. Please note that custom fields are not yet supported by the api although the backend supports them. -name: Users From a28f9cc987b9b4a5bfa9bc081c4ddcdd664c5849 Mon Sep 17 00:00:00 2001 From: Eric Schubert Date: Mon, 26 Aug 2024 15:52:59 +0200 Subject: [PATCH 2/3] [#40945] add meaningful examples to the form endpoints --- .../work_package_create_only_subject.yml | 5 +++ .../examples/work_package_create_valid.yml | 20 +++++++++++ .../examples/work_package_edit_subject.yml | 4 +++ .../schemas/work_package_form_model.yml | 7 ++-- .../schemas/work_package_write_model.yml | 3 ++ docs/api/apiv3/openapi-spec.yml | 6 ++++ .../paths/project_work_packages_form.yml | 9 +++-- docs/api/apiv3/paths/work_package_form.yml | 13 ++++--- docs/api/apiv3/paths/work_packages_form.yml | 36 +++++++++++++++---- 9 files changed, 86 insertions(+), 17 deletions(-) create mode 100644 docs/api/apiv3/components/examples/work_package_create_only_subject.yml create mode 100644 docs/api/apiv3/components/examples/work_package_create_valid.yml create mode 100644 docs/api/apiv3/components/examples/work_package_edit_subject.yml diff --git a/docs/api/apiv3/components/examples/work_package_create_only_subject.yml b/docs/api/apiv3/components/examples/work_package_create_only_subject.yml new file mode 100644 index 000000000000..39f3795735f8 --- /dev/null +++ b/docs/api/apiv3/components/examples/work_package_create_only_subject.yml @@ -0,0 +1,5 @@ +description: |- + A request body to create a work package with only a subject. This can only be used, if the project context is already + given in the path. All other values will fall back to defaults. +value: + subject: Replace GNK power droids diff --git a/docs/api/apiv3/components/examples/work_package_create_valid.yml b/docs/api/apiv3/components/examples/work_package_create_valid.yml new file mode 100644 index 000000000000..0e251cf18537 --- /dev/null +++ b/docs/api/apiv3/components/examples/work_package_create_valid.yml @@ -0,0 +1,20 @@ +description: |- + A valid request body to create or edit a work package with a couple of properties. +value: + subject: Install Dromund Kass planetary shield + description: + format: markdown + raw: |- + # TODO + + The planetary shield of Dromund Kass needs to be installed to protect the planet from orbital bombardment. + startDate: '2877-07-21' + duration: P1337D + estimatedTime: P1Y5DT13H + ignoreNonWorkingDays: true + project: + href: /api/v3/projects/42 + type: + href: /api/v3/types/13 + status: + href: /api/v3/statuses/2 diff --git a/docs/api/apiv3/components/examples/work_package_edit_subject.yml b/docs/api/apiv3/components/examples/work_package_edit_subject.yml new file mode 100644 index 000000000000..ec3c65b384eb --- /dev/null +++ b/docs/api/apiv3/components/examples/work_package_edit_subject.yml @@ -0,0 +1,4 @@ +description: |- + A request body to edit a work package's subject. +value: + subject: Replace GNK power droids diff --git a/docs/api/apiv3/components/schemas/work_package_form_model.yml b/docs/api/apiv3/components/schemas/work_package_form_model.yml index 16b7bfb11ce2..e9c957f26e6b 100644 --- a/docs/api/apiv3/components/schemas/work_package_form_model.yml +++ b/docs/api/apiv3/components/schemas/work_package_form_model.yml @@ -17,11 +17,10 @@ properties: schema: $ref: './work_package_schema_model.yml' validationErrors: - type: array - items: - type: object + type: object description: |- - A list of validation errors. This list is empty, if the request body is valid. + All validation errors, where the key is the faulty property. The object is empty, if the request body is + valid. _links: type: object properties: diff --git a/docs/api/apiv3/components/schemas/work_package_write_model.yml b/docs/api/apiv3/components/schemas/work_package_write_model.yml index 990dbb4ff9de..f0893ae3ff4f 100644 --- a/docs/api/apiv3/components/schemas/work_package_write_model.yml +++ b/docs/api/apiv3/components/schemas/work_package_write_model.yml @@ -1,6 +1,9 @@ # Schema: WorkPackageWriteModel --- type: object +description: |- + This model is used for creating and updating work packages. It can also be used for validation against the work + package form endpoints. properties: subject: type: string diff --git a/docs/api/apiv3/openapi-spec.yml b/docs/api/apiv3/openapi-spec.yml index e558237e6b90..c9ffc28257e3 100644 --- a/docs/api/apiv3/openapi-spec.yml +++ b/docs/api/apiv3/openapi-spec.yml @@ -567,6 +567,12 @@ components: $ref: "./components/examples/view_work_packages_table.yml" ViewTeamPlanner: $ref: "./components/examples/view_team_planner.yml" + WorkPackageCreateOnlySubject: + $ref: "./components/examples/work_package_create_only_subject.yml" + WorkPackageCreateValid: + $ref: "./components/examples/work_package_create_valid.yml" + WorkPackageEditSubject: + $ref: "./components/examples/work_package_edit_subject.yml" responses: InvalidQuery: diff --git a/docs/api/apiv3/paths/project_work_packages_form.yml b/docs/api/apiv3/paths/project_work_packages_form.yml index 86321426ba93..382d36624080 100644 --- a/docs/api/apiv3/paths/project_work_packages_form.yml +++ b/docs/api/apiv3/paths/project_work_packages_form.yml @@ -1,8 +1,8 @@ # /api/v3/projects/{id}/work_packages/form --- post: - summary: Work Package Create Form For Project - operationId: Work_Package_Create_Form_For_Project + summary: Form for creating Work Packages in a Project + operationId: form_create_work_package_in_project tags: - Work Packages description: |- @@ -22,6 +22,11 @@ post: application/json: schema: $ref: '../components/schemas/work_package_write_model.yml' + examples: + 'Minimal example': + $ref: '../components/examples/work_package_create_only_subject.yml' + 'Valid example': + $ref: '../components/examples/work_package_create_valid.yml' responses: '200': description: OK diff --git a/docs/api/apiv3/paths/work_package_form.yml b/docs/api/apiv3/paths/work_package_form.yml index 0e0d6fad2995..64870d121d5a 100644 --- a/docs/api/apiv3/paths/work_package_form.yml +++ b/docs/api/apiv3/paths/work_package_form.yml @@ -1,16 +1,16 @@ # /api/v3/work_packages/{id}/form --- post: - summary: Work Package Edit Form - operationId: Work_Package_Edit_Form + summary: Form for editing a Work Package + operationId: form_edit_work_package tags: - Work Packages description: |- When calling this endpoint, the client provides a single object containing the properties and links to be - created, in the body. The input is validated and a schema response is returned. If the validation errors of the - response is empty, the same payload can be used to create a work package. + edited, in the body. The input is validated and a schema response is returned. If the validation errors of the + response is empty, the same payload can be used to edit the work package. - Only the properties of the work package write model are allowed to set on a work package on creation. + Only the properties of the work package write model are allowed to set on a work package on editing. When setting start date, finish date, and duration together, their correctness will be checked and a validation error will be returned if one value does not match with the two others. You can make the server compute a value: @@ -22,6 +22,9 @@ post: application/json: schema: $ref: '../components/schemas/work_package_write_model.yml' + examples: + 'Changing subject': + $ref: '../components/examples/work_package_edit_subject.yml' parameters: - name: id description: ID of the work package being modified diff --git a/docs/api/apiv3/paths/work_packages_form.yml b/docs/api/apiv3/paths/work_packages_form.yml index a9c2d3541957..4998b9a41810 100644 --- a/docs/api/apiv3/paths/work_packages_form.yml +++ b/docs/api/apiv3/paths/work_packages_form.yml @@ -1,12 +1,36 @@ # /api/v3/work_packages/form --- post: + summary: Form for creating a Work Package + operationId: form_create_work_package + tags: + - Work Packages + description: |- + When calling this endpoint, the client provides a single object containing the properties and links to be + created, in the body. The input is validated and a schema response is returned. If the validation errors of the + response is empty, the same payload can be used to create a work package. + + Only the properties of the work package write model are allowed to set on a work package on creation. + + When setting start date, finish date, and duration together, their correctness will be checked and a validation + error will be returned if one value does not match with the two others. You can make the server compute a value: + set only two values in the request and the third one will be computed and returned in the response. For instance, + when sending `{ "startDate": "2022-08-23", duration: "P2D" }`, the response will + include `{ "dueDate": "2022-08-24" }`. + requestBody: + content: + application/json: + schema: + $ref: '../components/schemas/work_package_write_model.yml' + examples: + 'Valid creation': + $ref: '../components/examples/work_package_create_valid.yml' responses: '200': description: OK - headers: {} - tags: - - Work Packages - description: '' - operationId: Work_Package_Create_Form - summary: Work Package Create Form + content: + application/json: + schema: + $ref: '../components/schemas/work_package_form_model.yml' + '415': + $ref: '../components/responses/unsupported_media_type.yml' From f4ae455c0795836f61fbaf8a4d98cadb9fbf9b1d Mon Sep 17 00:00:00 2001 From: Eric Schubert Date: Mon, 26 Aug 2024 15:57:26 +0200 Subject: [PATCH 3/3] [#40945] readd 404 on edit form endpoint --- docs/api/apiv3/paths/work_package_form.yml | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/api/apiv3/paths/work_package_form.yml b/docs/api/apiv3/paths/work_package_form.yml index 64870d121d5a..911944a29c33 100644 --- a/docs/api/apiv3/paths/work_package_form.yml +++ b/docs/api/apiv3/paths/work_package_form.yml @@ -40,5 +40,20 @@ post: application/json: schema: $ref: '../components/schemas/work_package_form_model.yml' + '404': + 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 + content: + application/hal+json: + schema: + $ref: '../components/schemas/error_response.yml' + examples: + response: + value: + _type: Error + errorIdentifier: urn:openproject-org:api:v3:errors:NotFound + message: The specified work package does not exist. '415': $ref: '../components/responses/unsupported_media_type.yml'