From ca626a3ffa42d8563dba56294d42a7f54883c178 Mon Sep 17 00:00:00 2001 From: Gunter Ohrner Date: Thu, 20 Jan 2022 14:22:17 +0100 Subject: [PATCH 1/3] Improve `watchers_model.yml` and `work_packages_model.yml` Open question: `work_packages_by_project_model.yml` is structurally identical to `work_packages_model.yml`, the only difference is the embedded `example:`. I can imagine that it's important, due to the focus on API doc generation from this spec, so one option would be to just reference the `work_packages_model.yml` for the structural definition, avoiding redundancy for this, but in this case leaving the redundancy in the `example:` definition, with all possible drawbacks (inconsistencies etc.) Another approach would be to get rid of `work_packages_by_project_model.yml` completely and just using the generic `work_packages_model.yml` everywhere where we have a list of Work Packages. --- .../components/schemas/watchers_model.yml | 37 +++++++++++++++++++ .../work_packages_by_project_model.yml | 2 +- .../schemas/work_packages_model.yml | 37 +++++++++++++++++++ 3 files changed, 75 insertions(+), 1 deletion(-) diff --git a/docs/api/apiv3/components/schemas/watchers_model.yml b/docs/api/apiv3/components/schemas/watchers_model.yml index 0438905e77..5b2983c8aa 100644 --- a/docs/api/apiv3/components/schemas/watchers_model.yml +++ b/docs/api/apiv3/components/schemas/watchers_model.yml @@ -1,6 +1,43 @@ # Schema: WatchersModel --- type: object +properties: + total: + type: integer + description: Total number of entries + readOnly: true + minimum: 0 + exclusiveMinimum: false + count: + type: integer + description: Embedded number of entries + readOnly: true + minimum: 0 + exclusiveMinimum: false + _links: + type: object + required: + - self + properties: + self: + allOf: + - "$ref": "./link.yml" + - description: |- + The watcher list + + **Resource**: WatchersModel + readOnly: true + _embedded: + type: object + properties: + elements: + type: array + readOnly: true + items: + allOf: + - "$ref": "./user_model.yml" + - description: Collection of Users + readOnly: true example: _links: self: diff --git a/docs/api/apiv3/components/schemas/work_packages_by_project_model.yml b/docs/api/apiv3/components/schemas/work_packages_by_project_model.yml index fff3f0dc11..4793e88665 100644 --- a/docs/api/apiv3/components/schemas/work_packages_by_project_model.yml +++ b/docs/api/apiv3/components/schemas/work_packages_by_project_model.yml @@ -1,6 +1,6 @@ # Schema: Work_Packages_by_ProjectModel --- -type: object +$ref: "./work_packages_model.yml" example: _links: self: diff --git a/docs/api/apiv3/components/schemas/work_packages_model.yml b/docs/api/apiv3/components/schemas/work_packages_model.yml index 77edb63a12..eb59fb2c59 100644 --- a/docs/api/apiv3/components/schemas/work_packages_model.yml +++ b/docs/api/apiv3/components/schemas/work_packages_model.yml @@ -1,6 +1,43 @@ # Schema: Work_PackagesModel --- type: object +properties: + total: + type: integer + description: Total number of entries + readOnly: true + minimum: 0 + exclusiveMinimum: false + count: + type: integer + description: Embedded number of entries + readOnly: true + minimum: 0 + exclusiveMinimum: false + _links: + type: object + required: + - self + properties: + self: + allOf: + - "$ref": "./link.yml" + - description: |- + This Work Package List + + **Resource**: Work_PackagesModel + readOnly: true + _embedded: + type: object + properties: + elements: + type: array + readOnly: true + items: + allOf: + - "$ref": "./work_package_model.yml" + - description: Collection of WorkPackages + readOnly: true example: _links: self: From 84b9a3e0b5954c6d12ee17f2c09c1eb479af3ed4 Mon Sep 17 00:00:00 2001 From: Gunter Ohrner Date: Sat, 19 Mar 2022 23:06:39 +0100 Subject: [PATCH 2/3] Incorporated review remarks from Kharonus. Thanks for the review! See PR https://github.com/opf/openproject/pull/10179 for details. --- .../components/schemas/watchers_model.yml | 61 ++++++++----------- .../work_packages_by_project_model.yml | 24 -------- docs/api/apiv3/openapi-spec.yml | 2 - .../api/apiv3/paths/project_work_packages.yml | 2 +- 4 files changed, 28 insertions(+), 61 deletions(-) delete mode 100644 docs/api/apiv3/components/schemas/work_packages_by_project_model.yml diff --git a/docs/api/apiv3/components/schemas/watchers_model.yml b/docs/api/apiv3/components/schemas/watchers_model.yml index 5b2983c8aa..dba67d068e 100644 --- a/docs/api/apiv3/components/schemas/watchers_model.yml +++ b/docs/api/apiv3/components/schemas/watchers_model.yml @@ -1,43 +1,36 @@ # Schema: WatchersModel --- -type: object -properties: - total: - type: integer - description: Total number of entries - readOnly: true - minimum: 0 - exclusiveMinimum: false - count: - type: integer - description: Embedded number of entries - readOnly: true - minimum: 0 - exclusiveMinimum: false - _links: - type: object +allOf: + - "$ref": "./collection_model.yml" + - type: object required: - - self - properties: - self: - allOf: - - "$ref": "./link.yml" - - description: |- - The watcher list - - **Resource**: WatchersModel - readOnly: true - _embedded: - type: object + - _links + - _embedded properties: - elements: - type: array - readOnly: true - items: + _links: + type: object + required: + - self + properties: + self: allOf: - - "$ref": "./user_model.yml" - - description: Collection of Users + - "$ref": "./link.yml" + - description: |- + The watcher list + + **Resource**: WatchersModel + readOnly: true + _embedded: + type: object + properties: + elements: + type: array readOnly: true + items: + allOf: + - "$ref": "./user_model.yml" + - description: Collection of Users + readOnly: true example: _links: self: diff --git a/docs/api/apiv3/components/schemas/work_packages_by_project_model.yml b/docs/api/apiv3/components/schemas/work_packages_by_project_model.yml deleted file mode 100644 index 4793e88665..0000000000 --- a/docs/api/apiv3/components/schemas/work_packages_by_project_model.yml +++ /dev/null @@ -1,24 +0,0 @@ -# Schema: Work_Packages_by_ProjectModel ---- -$ref: "./work_packages_model.yml" -example: - _links: - self: - href: "/api/v3/projects/14/work_packages" - total: 2 - count: 2 - _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 diff --git a/docs/api/apiv3/openapi-spec.yml b/docs/api/apiv3/openapi-spec.yml index 0b70eb3827..65d43a995b 100644 --- a/docs/api/apiv3/openapi-spec.yml +++ b/docs/api/apiv3/openapi-spec.yml @@ -759,8 +759,6 @@ components: "$ref": "./components/schemas/work_package_activities_model.yml" Work_PackagesModel: "$ref": "./components/schemas/work_packages_model.yml" - Work_Packages_by_ProjectModel: - "$ref": "./components/schemas/work_packages_by_project_model.yml" securitySchemes: BasicAuth: type: http diff --git a/docs/api/apiv3/paths/project_work_packages.yml b/docs/api/apiv3/paths/project_work_packages.yml index dd22bd7d78..fe03b6d620 100644 --- a/docs/api/apiv3/paths/project_work_packages.yml +++ b/docs/api/apiv3/paths/project_work_packages.yml @@ -96,7 +96,7 @@ get: count: 2 total: 2 schema: - "$ref": "../components/schemas/work_packages_by_project_model.yml" + "$ref": "../components/schemas/work_packages_model.yml" description: OK headers: {} '400': From e2c79a80ac7cdeddf081bdc7ecf8c6775cd49e87 Mon Sep 17 00:00:00 2001 From: Gunter Ohrner Date: Tue, 22 Mar 2022 16:58:59 +0100 Subject: [PATCH 3/3] Incorporated review remark from Kharonus. https://github.com/opf/openproject/pull/10179#discussion_r832310381 --- docs/api/apiv3/components/schemas/watchers_model.yml | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/api/apiv3/components/schemas/watchers_model.yml b/docs/api/apiv3/components/schemas/watchers_model.yml index dba67d068e..f3f4759788 100644 --- a/docs/api/apiv3/components/schemas/watchers_model.yml +++ b/docs/api/apiv3/components/schemas/watchers_model.yml @@ -27,10 +27,9 @@ allOf: type: array readOnly: true items: - allOf: - - "$ref": "./user_model.yml" - - description: Collection of Users - readOnly: true + allOf: + - "$ref": "./user_model.yml" + - description: Collection of Users example: _links: self: