From c7062bd05974dbcecbde017f233a354c28b8888c Mon Sep 17 00:00:00 2001 From: Eric Schubert Date: Mon, 2 Sep 2024 13:30:29 +0200 Subject: [PATCH 1/2] [#57016] updated status API specification - https://community.openproject.org/work_packages/57016 --- .../components/examples/status_collection.yml | 91 +++++++++++-------- .../components/examples/status_response.yml | 16 ++++ .../schemas/status_collection_model.yml | 13 --- .../apiv3/components/schemas/status_model.yml | 55 +++++------ docs/api/apiv3/openapi-spec.yml | 10 +- docs/api/apiv3/paths/status.yml | 65 ++++++------- docs/api/apiv3/paths/statuses.yml | 28 +++--- 7 files changed, 146 insertions(+), 132 deletions(-) create mode 100644 docs/api/apiv3/components/examples/status_response.yml diff --git a/docs/api/apiv3/components/examples/status_collection.yml b/docs/api/apiv3/components/examples/status_collection.yml index c2756848fc2e..d12e01ba2aa5 100644 --- a/docs/api/apiv3/components/examples/status_collection.yml +++ b/docs/api/apiv3/components/examples/status_collection.yml @@ -1,72 +1,89 @@ -# Example: Status collection ---- +description: |- + A standard, unpaginated collection of status. value: + _type: Collection + count: 6 + total: 6 _embedded: elements: - - _links: - self: - href: "/api/v3/statuses/1" - _type: Status - defaultDoneRatio: 0 + - _type: Status id: 1 + name: New isClosed: false + color: '#3997AD' isDefault: true - name: New + isReadonly: false + excludedFromTotals: false + defaultDoneRatio: 0 position: 1 - - _links: + _links: self: - href: "/api/v3/statuses/3" - _type: Status - defaultDoneRatio: 75 + href: '/api/v3/statuses/1' + - _type: Status id: 3 + name: Resolved isClosed: false + color: '#93D2AE' isDefault: false isReadonly: false - name: Resolved + excludedFromTotals: false + defaultDoneRatio: 75 position: 3 - - _links: + _links: self: - href: "/api/v3/statuses/4" - _type: Status - defaultDoneRatio: 25 + href: '/api/v3/statuses/3' + - _type: Status id: 4 + name: Feedback isClosed: false + color: '#A96FFE' isDefault: false - name: Feedback + isReadonly: false + excludedFromTotals: false + defaultDoneRatio: 25 position: 4 - - _links: + _links: self: - href: "/api/v3/statuses/5" - _type: Status - defaultDoneRatio: 100 + href: '/api/v3/statuses/4' + - _type: Status id: 5 + name: Closed isClosed: true + color: '#DF6DA1' isDefault: false - name: Closed + isReadonly: false + excludedFromTotals: false + defaultDoneRatio: 100 position: 5 - - _links: + _links: self: - href: "/api/v3/statuses/6" - _type: Status - defaultDoneRatio: 100 + href: '/api/v3/statuses/5' + - _type: Status id: 6 + name: Rejected isClosed: true + color: '#D32937' isDefault: false - name: Rejected + isReadonly: true + excludedFromTotals: true + defaultDoneRatio: 100 position: 6 - - _links: + _links: self: - href: "/api/v3/statuses/2" - _type: Status - defaultDoneRatio: 50 + href: '/api/v3/statuses/6' + - _type: Status id: 2 + name: In Progress isClosed: false + color: '#3852C6' isDefault: false - name: In Progress + isReadonly: false + excludedFromTotals: false + defaultDoneRatio: 50 position: 3 + _links: + self: + href: '/api/v3/statuses/2' _links: self: - href: "/api/v3/statuses" - _type: Collection - count: 6 - total: 6 + href: '/api/v3/statuses' diff --git a/docs/api/apiv3/components/examples/status_response.yml b/docs/api/apiv3/components/examples/status_response.yml new file mode 100644 index 000000000000..7a132dd9bf1f --- /dev/null +++ b/docs/api/apiv3/components/examples/status_response.yml @@ -0,0 +1,16 @@ +description: A standard status resource response. +value: + _type: Status + id: 13 + name: Waiting for Darth-approval + isClosed: false + color: '#FE005D' + isDefault: false + isReadonly: false + excludedFromTotals: false + defaultDoneRatio: 66 + position: 4 + _links: + self: + href: '/api/v3/statuses/13' + title: Waiting for Darth-approval diff --git a/docs/api/apiv3/components/schemas/status_collection_model.yml b/docs/api/apiv3/components/schemas/status_collection_model.yml index f4031bf22c1f..ee670be3528c 100644 --- a/docs/api/apiv3/components/schemas/status_collection_model.yml +++ b/docs/api/apiv3/components/schemas/status_collection_model.yml @@ -4,21 +4,8 @@ allOf: - $ref: './collection_model.yml' - type: object required: - - _links - _embedded properties: - _links: - type: object - required: - - self - properties: - self: - allOf: - - $ref: './link.yml' - - description: |- - This file links collection - - **Resource**: StatusCollectionModel _embedded: type: object required: diff --git a/docs/api/apiv3/components/schemas/status_model.yml b/docs/api/apiv3/components/schemas/status_model.yml index da3f9113e6fd..e17ae6384235 100644 --- a/docs/api/apiv3/components/schemas/status_model.yml +++ b/docs/api/apiv3/components/schemas/status_model.yml @@ -9,52 +9,45 @@ properties: id: type: integer description: Status id - readOnly: true minimum: 1 name: type: string description: Status name - readOnly: true - position: - type: integer - description: Sort index of the status - readOnly: true - isDefault: - type: boolean - readOnly: true isClosed: type: boolean - description: are tickets of this status considered closed? - readOnly: true + description: Indicates, whether work package of this status are considered closed + color: + type: string + format: hex-code + description: The color of the status + isDefault: + type: boolean + description: True, if this status is the default status for new work packages isReadonly: type: boolean - description: are tickets of this status read only? - readOnly: true + description: Indicates, whether work package of this status are readonly + excludedFromTotals: + type: boolean + description: |- + Indicates, whether work package of this status are excluded from totals of `Work`, `Remaining work`, and + `% Complete` in a hierarchy. defaultDoneRatio: type: integer description: The percentageDone being applied when changing to this status + minimum: 0 maximum: 100 + position: + type: integer + description: Sort index of the status _links: type: object required: - - self + - self properties: self: allOf: - - "$ref": "./link.yml" - - description: |- - This status - - **Resource**: Status - readOnly: true -example: - _links: - self: - href: "/api/v3/statuses/1" - _type: Status - id: 1 - name: New - position: 1 - isDefault: true - isClosed: false - defaultDoneRatio: 0 + - $ref: './link.yml' + - description: |- + This status + + **Resource**: Status diff --git a/docs/api/apiv3/openapi-spec.yml b/docs/api/apiv3/openapi-spec.yml index c9ffc28257e3..9175c3f08b8b 100644 --- a/docs/api/apiv3/openapi-spec.yml +++ b/docs/api/apiv3/openapi-spec.yml @@ -527,6 +527,10 @@ components: $ref: "./components/examples/relation_response.yml" RelationUpdateRequest: $ref: "./components/examples/relation_update_request.yml" + StatusCollection: + $ref: "./components/examples/status_collection.yml" + StatusResponse: + $ref: "./components/examples/status_response.yml" StorageNextcloudResponse: $ref: "./components/examples/storage-nextcloud-response.yml" StorageNextcloudResponseForCreation: @@ -537,16 +541,14 @@ components: $ref: "./components/examples/storage-one-drive-incomplete-response.yml" StorageOneDriveResponse: $ref: "./components/examples/storage-one-drive-response.yml" + StoragesSimpleCollectionModel: + $ref: "./components/examples/storages-simple-collection-response.yml" QueriesModel: $ref: "./components/examples/queries.yml" QueryModel: $ref: "./components/examples/query.yml" QuerySchemaModel: $ref: "./components/examples/query_schema.yml" - StatusCollection: - $ref: "./components/examples/status_collection.yml" - StoragesSimpleCollectionModel: - $ref: "./components/examples/storages-simple-collection-response.yml" UserResponse: $ref: "./components/examples/user-response.yml" ValuesPropertyStartDateSchema: diff --git a/docs/api/apiv3/paths/status.yml b/docs/api/apiv3/paths/status.yml index b20d4d852b34..5edf3a96530f 100644 --- a/docs/api/apiv3/paths/status.yml +++ b/docs/api/apiv3/paths/status.yml @@ -1,53 +1,54 @@ # /api/v3/statuses/{id} --- get: + summary: Get a work package status + operationId: get_status + tags: + - Statuses + description: |- + Returns a work package status by its unique identifier. parameters: - - description: Status id - example: '1' - in: path - name: id - required: true - schema: - type: integer + - name: id + description: Status id + in: path + required: true + schema: + type: integer + example: '1' responses: '200': + description: OK content: application/hal+json: examples: response: - value: - _links: - self: - href: "/api/v3/statuses/1" - _type: Status - defaultDoneRatio: 0 - id: 1 - isClosed: false - isDefault: true - name: New - position: 1 + $ref: '../components/examples/status_response.yml' schema: - "$ref": "../components/schemas/status_model.yml" - description: OK - headers: {} + $ref: '../components/schemas/status_model.yml' '403': + description: |- + Returned if the client does not have sufficient permissions. + + **Required permission:** view work package (on any project) content: application/hal+json: schema: - $ref: "../components/schemas/error_response.yml" + $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 see this status. - description: |- - Returned if the client does not have sufficient permissions. - - **Required permission:** view work package (on any project) - headers: {} - tags: - - Statuses - description: '' - operationId: View_Status - summary: View Status + '404': + description: Returned if the status does not exist. + 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 requested resource could not be found. diff --git a/docs/api/apiv3/paths/statuses.yml b/docs/api/apiv3/paths/statuses.yml index 557b4a7c987f..8468298e75b3 100644 --- a/docs/api/apiv3/paths/statuses.yml +++ b/docs/api/apiv3/paths/statuses.yml @@ -1,35 +1,33 @@ # /api/v3/statuses --- get: + summary: List the collection of all status + operationId: list_status + tags: + - Statuses + description: Returns a collection of all work package status. responses: '200': + description: OK content: application/hal+json: examples: 'simple status collection': - $ref: "../components/examples/status_collection.yml" + $ref: '../components/examples/status_collection.yml' schema: - "$ref": "../components/schemas/status_collection_model.yml" - description: OK - headers: {} + $ref: '../components/schemas/status_collection_model.yml' '403': + description: |- + Returned if the client does not have sufficient permissions. + + **Required permission:** view work package (on any project) content: application/hal+json: schema: - $ref: "../components/schemas/error_response.yml" + $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 see the statuses. - description: |- - Returned if the client does not have sufficient permissions. - - **Required permission:** view work package (on any project) - headers: {} - tags: - - Statuses - description: '' - operationId: List_all_Statuses - summary: List all Statuses From 66dc5a8130b8d0edf39a9c11ee508fb7a2746409 Mon Sep 17 00:00:00 2001 From: Eric Schubert Date: Tue, 3 Sep 2024 11:55:08 +0200 Subject: [PATCH 2/2] [#57016] updated statuses tag - use plural statuses everywhere in api spec --- .../components/examples/status_collection.yml | 2 +- docs/api/apiv3/paths/statuses.yml | 6 ++-- docs/api/apiv3/tags/statuses.yml | 29 ++++++++++--------- 3 files changed, 19 insertions(+), 18 deletions(-) diff --git a/docs/api/apiv3/components/examples/status_collection.yml b/docs/api/apiv3/components/examples/status_collection.yml index d12e01ba2aa5..a5802fb8d246 100644 --- a/docs/api/apiv3/components/examples/status_collection.yml +++ b/docs/api/apiv3/components/examples/status_collection.yml @@ -1,5 +1,5 @@ description: |- - A standard, unpaginated collection of status. + A standard, unpaginated collection of statuses. value: _type: Collection count: 6 diff --git a/docs/api/apiv3/paths/statuses.yml b/docs/api/apiv3/paths/statuses.yml index 8468298e75b3..c7878c8e6d90 100644 --- a/docs/api/apiv3/paths/statuses.yml +++ b/docs/api/apiv3/paths/statuses.yml @@ -1,11 +1,11 @@ # /api/v3/statuses --- get: - summary: List the collection of all status - operationId: list_status + summary: List the collection of all statuses + operationId: list_statuses tags: - Statuses - description: Returns a collection of all work package status. + description: Returns a collection of all work package statuses. responses: '200': description: OK diff --git a/docs/api/apiv3/tags/statuses.yml b/docs/api/apiv3/tags/statuses.yml index c1b46ecf5ae5..a8623c757a13 100644 --- a/docs/api/apiv3/tags/statuses.yml +++ b/docs/api/apiv3/tags/statuses.yml @@ -1,20 +1,21 @@ ---- +name: Statuses description: |- ## Linked Properties - | Link | Description | Type | Constraints | Supported operations | - |:-------------:|-------------------------- | ------------- | ----------- | -------------------- | - | self | This status | Status | not null | READ | + | Link | Description | Type | Constraints | Supported operations | + |:----:|-------------|--------|-------------|----------------------| + | self | This status | Status | not null | READ | ## Local Properties - | Property | Description | Type | Constraints | Supported operations | - | :--------: | ------------- | ------- | ----------- | -------------------- | - | id | Status id | Integer | x > 0 | READ | - | name | Status name | String | | READ | - | position | Sort index of the status | Integer | | READ | - | isDefault | | Boolean | | READ | - | isClosed | are tickets of this status considered closed? | Boolean | | READ | - | isReadonly | are tickets of this status read only? | Boolean | | READ | - | defaultDoneRatio | The percentageDone being applied when changing to this status | Integer | 0 <= x <= 100 | READ | -name: Statuses + | Property | Description | Type | Constraints | Supported operations | + |:------------------:|--------------------------------------------------------------------------------------------------------------------------------------------|---------|---------------|----------------------| + | id | Status id | Integer | x > 0 | READ | + | name | Status name | String | | READ | + | isClosed | Indicates, whether work package of this status are considered closed | Boolean | | READ | + | color | A Hex-coded value of the color assigned to the status. | String | | READ | + | isDefault | True, if this status is the default status for new work packages | Boolean | | READ | + | isReadonly | Indicates, whether work package of this status are readonly | Boolean | | READ | + | excludedFromTotals | Indicates, whether work package of this status are excluded from totals of
`Work`, `Remaining work`, and `% Complete` in a hierarchy. | Boolean | | READ | + | defaultDoneRatio | The percentageDone being applied when changing to this status | Integer | 0 <= x <= 100 | READ | + | position | Sort index of the status | Integer | | READ |