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