From ccdaa9f534b5064dcb4f99e06d1a7286e021fda6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Oliver=20G=C3=BCnther?= Date: Mon, 8 Jun 2026 12:59:10 +0200 Subject: [PATCH] Update openapi docs --- docs/api/apiv3/openapi-spec.yml | 16 +- docs/api/apiv3/paths/meeting_agenda_item.yml | 55 +------ .../paths/meeting_agenda_item_by_meeting.yml | 43 ++++++ .../paths/meeting_agenda_item_outcome.yml | 142 +----------------- .../paths/meeting_agenda_item_outcomes.yml | 73 --------- docs/api/apiv3/paths/meeting_agenda_items.yml | 51 +------ .../paths/meeting_agenda_items_by_meeting.yml | 38 +++++ docs/api/apiv3/paths/meeting_outcome.yml | 124 +++++++++++++++ docs/api/apiv3/paths/meeting_outcomes.yml | 59 ++++++++ docs/api/apiv3/paths/meeting_section.yml | 65 +------- .../paths/meeting_section_by_meeting.yml | 43 ++++++ docs/api/apiv3/paths/meeting_sections.yml | 51 +------ .../paths/meeting_sections_by_meeting.yml | 38 +++++ 13 files changed, 378 insertions(+), 420 deletions(-) create mode 100644 docs/api/apiv3/paths/meeting_agenda_item_by_meeting.yml create mode 100644 docs/api/apiv3/paths/meeting_agenda_items_by_meeting.yml create mode 100644 docs/api/apiv3/paths/meeting_outcome.yml create mode 100644 docs/api/apiv3/paths/meeting_outcomes.yml create mode 100644 docs/api/apiv3/paths/meeting_section_by_meeting.yml create mode 100644 docs/api/apiv3/paths/meeting_sections_by_meeting.yml diff --git a/docs/api/apiv3/openapi-spec.yml b/docs/api/apiv3/openapi-spec.yml index c47cf84d2ad..a23b2192a10 100644 --- a/docs/api/apiv3/openapi-spec.yml +++ b/docs/api/apiv3/openapi-spec.yml @@ -272,20 +272,32 @@ paths: "/api/v3/meetings/{id}": "$ref": "./paths/meeting.yml" "/api/v3/meetings/{id}/agenda_items": - "$ref": "./paths/meeting_agenda_items.yml" + "$ref": "./paths/meeting_agenda_items_by_meeting.yml" "/api/v3/meetings/{meeting_id}/agenda_items/{id}": + "$ref": "./paths/meeting_agenda_item_by_meeting.yml" + "/api/v3/meeting_agenda_items": + "$ref": "./paths/meeting_agenda_items.yml" + "/api/v3/meeting_agenda_items/{id}": "$ref": "./paths/meeting_agenda_item.yml" "/api/v3/meetings/{meeting_id}/agenda_items/{agenda_item_id}/outcomes": "$ref": "./paths/meeting_agenda_item_outcomes.yml" "/api/v3/meetings/{meeting_id}/agenda_items/{agenda_item_id}/outcomes/{id}": "$ref": "./paths/meeting_agenda_item_outcome.yml" + "/api/v3/meeting_outcomes": + "$ref": "./paths/meeting_outcomes.yml" + "/api/v3/meeting_outcomes/{id}": + "$ref": "./paths/meeting_outcome.yml" "/api/v3/meetings/{id}/attachments": "$ref": "./paths/meeting_attachments.yml" "/api/v3/meetings/{id}/form": "$ref": "./paths/meeting_form.yml" "/api/v3/meetings/{id}/sections": - "$ref": "./paths/meeting_sections.yml" + "$ref": "./paths/meeting_sections_by_meeting.yml" "/api/v3/meetings/{meeting_id}/sections/{id}": + "$ref": "./paths/meeting_section_by_meeting.yml" + "/api/v3/meeting_sections": + "$ref": "./paths/meeting_sections.yml" + "/api/v3/meeting_sections/{id}": "$ref": "./paths/meeting_section.yml" "/api/v3/meetings/form": "$ref": "./paths/meetings_form.yml" diff --git a/docs/api/apiv3/paths/meeting_agenda_item.yml b/docs/api/apiv3/paths/meeting_agenda_item.yml index 4c11743260b..8f2de6626ed 100644 --- a/docs/api/apiv3/paths/meeting_agenda_item.yml +++ b/docs/api/apiv3/paths/meeting_agenda_item.yml @@ -1,19 +1,12 @@ -# /api/v3/meetings/{meeting_id}/agenda_items/{id} +# /api/v3/meeting_agenda_items/{id} --- get: summary: Get a meeting agenda item operationId: get_meeting_agenda_item tags: - Meetings - description: Retrieve an individual agenda item of a meeting. + description: Retrieve an individual agenda item. parameters: - - description: Meeting identifier - example: 1 - in: path - name: meeting_id - required: true - schema: - type: integer - description: Agenda item identifier example: 1 in: path @@ -40,7 +33,7 @@ get: errorIdentifier: urn:openproject-org:api:v3:errors:NotFound message: The requested resource could not be found. description: |- - Returned if the agenda item or meeting does not exist or the client does not have sufficient permissions. + Returned if the agenda item does not exist or the client does not have sufficient permissions. patch: summary: Update a meeting agenda item @@ -49,13 +42,6 @@ patch: - Meetings description: Updates the given agenda item. parameters: - - description: Meeting identifier - example: 1 - in: path - name: meeting_id - required: true - schema: - type: integer - description: Agenda item identifier example: 1 in: path @@ -82,12 +68,6 @@ patch: application/hal+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 authorized to access this resource. description: |- Returned if the client does not have sufficient permissions. @@ -97,14 +77,8 @@ patch: 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. description: |- - Returned if the agenda item or meeting does not exist. + Returned if the agenda item does not exist or the client does not have sufficient permissions. '406': $ref: "../components/responses/missing_content_type.yml" '415': @@ -122,13 +96,6 @@ delete: - Meetings description: Deletes the agenda item. parameters: - - description: Meeting identifier - example: 1 - in: path - name: meeting_id - required: true - schema: - type: integer - description: Agenda item identifier example: 1 in: path @@ -144,12 +111,6 @@ delete: application/hal+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 authorized to access this resource. description: |- Returned if the client does not have sufficient permissions. @@ -159,11 +120,5 @@ delete: 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. description: |- - Returned if the agenda item or meeting does not exist. + Returned if the agenda item does not exist or the client does not have sufficient permissions. diff --git a/docs/api/apiv3/paths/meeting_agenda_item_by_meeting.yml b/docs/api/apiv3/paths/meeting_agenda_item_by_meeting.yml new file mode 100644 index 00000000000..0067285a39e --- /dev/null +++ b/docs/api/apiv3/paths/meeting_agenda_item_by_meeting.yml @@ -0,0 +1,43 @@ +# /api/v3/meetings/{meeting_id}/agenda_items/{id} +--- +get: + summary: Get a meeting agenda item + operationId: get_meeting_agenda_item_by_meeting + tags: + - Meetings + description: Retrieve an individual agenda item of a meeting. + parameters: + - description: Meeting identifier + example: 1 + in: path + name: meeting_id + required: true + schema: + type: integer + - description: Agenda item identifier + example: 1 + in: path + name: id + required: true + schema: + type: integer + responses: + '200': + description: OK + content: + application/hal+json: + schema: + $ref: "../components/schemas/meeting_agenda_item_model.yml" + '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 requested resource could not be found. + description: |- + Returned if the agenda item or meeting does not exist or the client does not have sufficient permissions. diff --git a/docs/api/apiv3/paths/meeting_agenda_item_outcome.yml b/docs/api/apiv3/paths/meeting_agenda_item_outcome.yml index 00a6172cd06..c4622ca48b6 100644 --- a/docs/api/apiv3/paths/meeting_agenda_item_outcome.yml +++ b/docs/api/apiv3/paths/meeting_agenda_item_outcome.yml @@ -2,7 +2,7 @@ --- get: summary: Get a meeting outcome - operationId: get_meeting_outcome + operationId: get_meeting_outcome_by_agenda_item tags: - Meetings description: Retrieve an individual outcome of a meeting agenda item. @@ -48,143 +48,3 @@ get: message: The requested resource could not be found. description: |- Returned if the outcome, agenda item, or meeting does not exist or the client does not have sufficient permissions. - -patch: - summary: Update a meeting outcome - operationId: update_meeting_outcome - tags: - - Meetings - description: Updates the given meeting outcome. - parameters: - - description: Meeting identifier - example: 1 - in: path - name: meeting_id - required: true - schema: - type: integer - - description: Agenda item identifier - example: 1 - in: path - name: agenda_item_id - required: true - schema: - type: integer - - description: Outcome identifier - example: 1 - in: path - name: id - required: true - schema: - type: integer - requestBody: - content: - application/json: - schema: - $ref: "../components/schemas/meeting_outcome_write_model.yml" - responses: - '200': - description: OK - content: - application/hal+json: - schema: - $ref: "../components/schemas/meeting_outcome_model.yml" - '400': - $ref: "../components/responses/invalid_request_body.yml" - '403': - content: - application/hal+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 authorized to access this resource. - description: |- - Returned if the client does not have sufficient permissions. - - **Required permission:** manage outcomes - '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 requested resource could not be found. - description: |- - Returned if the outcome, agenda item, or meeting does not exist. - '406': - $ref: "../components/responses/missing_content_type.yml" - '415': - $ref: "../components/responses/unsupported_media_type.yml" - '422': - description: |- - Returned if: - - * a constraint for a property was violated (`PropertyConstraintViolation`) - -delete: - summary: Delete a meeting outcome - operationId: delete_meeting_outcome - tags: - - Meetings - description: Deletes the outcome. - parameters: - - description: Meeting identifier - example: 1 - in: path - name: meeting_id - required: true - schema: - type: integer - - description: Agenda item identifier - example: 1 - in: path - name: agenda_item_id - required: true - schema: - type: integer - - description: Outcome identifier - example: 1 - in: path - name: id - required: true - schema: - type: integer - responses: - '204': - description: Returned if the outcome was successfully deleted - '403': - content: - application/hal+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 authorized to access this resource. - description: |- - Returned if the client does not have sufficient permissions. - - **Required permission:** manage outcomes - '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 requested resource could not be found. - description: |- - Returned if the outcome, agenda item, or meeting does not exist. diff --git a/docs/api/apiv3/paths/meeting_agenda_item_outcomes.yml b/docs/api/apiv3/paths/meeting_agenda_item_outcomes.yml index 13f5b8f66be..32d096816b8 100644 --- a/docs/api/apiv3/paths/meeting_agenda_item_outcomes.yml +++ b/docs/api/apiv3/paths/meeting_agenda_item_outcomes.yml @@ -43,76 +43,3 @@ get: Returned if the agenda item or meeting does not exist or the client does not have sufficient permissions to see it. **Required permission:** view meetings - -post: - summary: Create meeting outcome - operationId: create_meeting_outcome - tags: - - Meetings - description: Creates a new outcome for the given meeting agenda item. - parameters: - - description: Meeting identifier - example: 1 - in: path - name: meeting_id - required: true - schema: - type: integer - - description: Agenda item identifier - example: 1 - in: path - name: agenda_item_id - required: true - schema: - type: integer - requestBody: - content: - application/json: - schema: - $ref: "../components/schemas/meeting_outcome_write_model.yml" - responses: - '201': - description: Created - content: - application/hal+json: - schema: - $ref: "../components/schemas/meeting_outcome_model.yml" - '400': - $ref: "../components/responses/invalid_request_body.yml" - '403': - content: - application/hal+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 authorized to access this resource. - description: |- - Returned if the client does not have sufficient permissions. - - **Required permission:** manage outcomes - '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 requested resource could not be found. - description: |- - Returned if the agenda item or meeting does not exist or the client does not have sufficient permissions to see it. - '406': - $ref: "../components/responses/missing_content_type.yml" - '415': - $ref: "../components/responses/unsupported_media_type.yml" - '422': - description: |- - Returned if: - - * a constraint for a property was violated (`PropertyConstraintViolation`) diff --git a/docs/api/apiv3/paths/meeting_agenda_items.yml b/docs/api/apiv3/paths/meeting_agenda_items.yml index 590180f157d..23bf5e6f549 100644 --- a/docs/api/apiv3/paths/meeting_agenda_items.yml +++ b/docs/api/apiv3/paths/meeting_agenda_items.yml @@ -1,56 +1,11 @@ -# /api/v3/meetings/{id}/agenda_items +# /api/v3/meeting_agenda_items --- -get: - summary: List meeting agenda items - operationId: list_meeting_agenda_items - tags: - - Meetings - description: Lists all agenda items for the given meeting. - parameters: - - description: Meeting identifier - example: 1 - in: path - name: id - required: true - schema: - type: integer - responses: - '200': - description: OK - content: - application/hal+json: - schema: - $ref: "../components/schemas/meeting_agenda_item_collection_model.yml" - '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 requested resource could not be found. - description: |- - Returned if the meeting does not exist or the client does not have sufficient permissions to see it. - - **Required permission:** view meetings - post: summary: Create meeting agenda item operationId: create_meeting_agenda_item tags: - Meetings - description: Creates a new agenda item for the given meeting. - parameters: - - description: Meeting identifier - example: 1 - in: path - name: id - required: true - schema: - type: integer + description: Creates a new agenda item. The request body must link the meeting. requestBody: content: application/json: @@ -92,7 +47,7 @@ post: errorIdentifier: urn:openproject-org:api:v3:errors:NotFound message: The requested resource could not be found. description: |- - Returned if the meeting does not exist or the client does not have sufficient permissions to see it. + Returned if the linked meeting does not exist or the client does not have sufficient permissions to see it. '406': $ref: "../components/responses/missing_content_type.yml" '415': diff --git a/docs/api/apiv3/paths/meeting_agenda_items_by_meeting.yml b/docs/api/apiv3/paths/meeting_agenda_items_by_meeting.yml new file mode 100644 index 00000000000..c49c9e7eb03 --- /dev/null +++ b/docs/api/apiv3/paths/meeting_agenda_items_by_meeting.yml @@ -0,0 +1,38 @@ +# /api/v3/meetings/{id}/agenda_items +--- +get: + summary: List meeting agenda items + operationId: list_meeting_agenda_items + tags: + - Meetings + description: Lists all agenda items for the given meeting. + parameters: + - description: Meeting identifier + example: 1 + in: path + name: id + required: true + schema: + type: integer + responses: + '200': + description: OK + content: + application/hal+json: + schema: + $ref: "../components/schemas/meeting_agenda_item_collection_model.yml" + '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 requested resource could not be found. + description: |- + Returned if the meeting does not exist or the client does not have sufficient permissions to see it. + + **Required permission:** view meetings diff --git a/docs/api/apiv3/paths/meeting_outcome.yml b/docs/api/apiv3/paths/meeting_outcome.yml new file mode 100644 index 00000000000..28581ff2423 --- /dev/null +++ b/docs/api/apiv3/paths/meeting_outcome.yml @@ -0,0 +1,124 @@ +# /api/v3/meeting_outcomes/{id} +--- +get: + summary: Get a meeting outcome + operationId: get_meeting_outcome + tags: + - Meetings + description: Retrieve an individual meeting outcome. + parameters: + - description: Outcome identifier + example: 1 + in: path + name: id + required: true + schema: + type: integer + responses: + '200': + description: OK + content: + application/hal+json: + schema: + $ref: "../components/schemas/meeting_outcome_model.yml" + '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 requested resource could not be found. + description: |- + Returned if the outcome does not exist or the client does not have sufficient permissions. + +patch: + summary: Update a meeting outcome + operationId: update_meeting_outcome + tags: + - Meetings + description: Updates the given meeting outcome. + parameters: + - description: Outcome identifier + example: 1 + in: path + name: id + required: true + schema: + type: integer + requestBody: + content: + application/json: + schema: + $ref: "../components/schemas/meeting_outcome_write_model.yml" + responses: + '200': + description: OK + content: + application/hal+json: + schema: + $ref: "../components/schemas/meeting_outcome_model.yml" + '400': + $ref: "../components/responses/invalid_request_body.yml" + '403': + content: + application/hal+json: + schema: + $ref: "../components/schemas/error_response.yml" + description: |- + Returned if the client does not have sufficient permissions. + + **Required permission:** manage outcomes + '404': + content: + application/hal+json: + schema: + $ref: "../components/schemas/error_response.yml" + description: |- + Returned if the outcome does not exist or the client does not have sufficient permissions. + '406': + $ref: "../components/responses/missing_content_type.yml" + '415': + $ref: "../components/responses/unsupported_media_type.yml" + '422': + description: |- + Returned if: + + * a constraint for a property was violated (`PropertyConstraintViolation`) + +delete: + summary: Delete a meeting outcome + operationId: delete_meeting_outcome + tags: + - Meetings + description: Deletes the outcome. + parameters: + - description: Outcome identifier + example: 1 + in: path + name: id + required: true + schema: + type: integer + responses: + '204': + description: Returned if the outcome was successfully deleted + '403': + content: + application/hal+json: + schema: + $ref: "../components/schemas/error_response.yml" + description: |- + Returned if the client does not have sufficient permissions. + + **Required permission:** manage outcomes + '404': + content: + application/hal+json: + schema: + $ref: "../components/schemas/error_response.yml" + description: |- + Returned if the outcome does not exist or the client does not have sufficient permissions. diff --git a/docs/api/apiv3/paths/meeting_outcomes.yml b/docs/api/apiv3/paths/meeting_outcomes.yml new file mode 100644 index 00000000000..4cf6088a753 --- /dev/null +++ b/docs/api/apiv3/paths/meeting_outcomes.yml @@ -0,0 +1,59 @@ +# /api/v3/meeting_outcomes +--- +post: + summary: Create meeting outcome + operationId: create_meeting_outcome + tags: + - Meetings + description: Creates a new meeting outcome. The request body must link the agenda item. + requestBody: + content: + application/json: + schema: + $ref: "../components/schemas/meeting_outcome_write_model.yml" + responses: + '201': + description: Created + content: + application/hal+json: + schema: + $ref: "../components/schemas/meeting_outcome_model.yml" + '400': + $ref: "../components/responses/invalid_request_body.yml" + '403': + content: + application/hal+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 authorized to access this resource. + description: |- + Returned if the client does not have sufficient permissions. + + **Required permission:** manage outcomes + '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 requested resource could not be found. + description: |- + Returned if the linked agenda item does not exist or the client does not have sufficient permissions to see it. + '406': + $ref: "../components/responses/missing_content_type.yml" + '415': + $ref: "../components/responses/unsupported_media_type.yml" + '422': + description: |- + Returned if: + + * a constraint for a property was violated (`PropertyConstraintViolation`) diff --git a/docs/api/apiv3/paths/meeting_section.yml b/docs/api/apiv3/paths/meeting_section.yml index 79c167db431..d06fc3dcb5c 100644 --- a/docs/api/apiv3/paths/meeting_section.yml +++ b/docs/api/apiv3/paths/meeting_section.yml @@ -1,19 +1,12 @@ -# /api/v3/meetings/{meeting_id}/sections/{id} +# /api/v3/meeting_sections/{id} --- get: summary: Get a meeting section operationId: get_meeting_section tags: - Meetings - description: Retrieve an individual section of a meeting. + description: Retrieve an individual meeting section. parameters: - - description: Meeting identifier - example: 1 - in: path - name: meeting_id - required: true - schema: - type: integer - description: Section identifier example: 1 in: path @@ -33,29 +26,16 @@ get: 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. description: |- - Returned if the section or meeting does not exist or the client does not have sufficient permissions. + Returned if the section does not exist or the client does not have sufficient permissions. patch: summary: Update a meeting section operationId: update_meeting_section tags: - Meetings - description: Updates the given section. + description: Updates the given meeting section. parameters: - - description: Meeting identifier - example: 1 - in: path - name: meeting_id - required: true - schema: - type: integer - description: Section identifier example: 1 in: path @@ -82,12 +62,6 @@ patch: application/hal+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 authorized to access this resource. description: |- Returned if the client does not have sufficient permissions. @@ -97,14 +71,8 @@ patch: 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. description: |- - Returned if the section or meeting does not exist. + Returned if the section does not exist or the client does not have sufficient permissions. '406': $ref: "../components/responses/missing_content_type.yml" '415': @@ -120,15 +88,8 @@ delete: operationId: delete_meeting_section tags: - Meetings - description: Deletes the section and all its agenda items. + description: Deletes the meeting section. parameters: - - description: Meeting identifier - example: 1 - in: path - name: meeting_id - required: true - schema: - type: integer - description: Section identifier example: 1 in: path @@ -144,12 +105,6 @@ delete: application/hal+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 authorized to access this resource. description: |- Returned if the client does not have sufficient permissions. @@ -159,11 +114,5 @@ delete: 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. description: |- - Returned if the section or meeting does not exist. + Returned if the section does not exist or the client does not have sufficient permissions. diff --git a/docs/api/apiv3/paths/meeting_section_by_meeting.yml b/docs/api/apiv3/paths/meeting_section_by_meeting.yml new file mode 100644 index 00000000000..6eaed2fc867 --- /dev/null +++ b/docs/api/apiv3/paths/meeting_section_by_meeting.yml @@ -0,0 +1,43 @@ +# /api/v3/meetings/{meeting_id}/sections/{id} +--- +get: + summary: Get a meeting section + operationId: get_meeting_section_by_meeting + tags: + - Meetings + description: Retrieve an individual section of a meeting. + parameters: + - description: Meeting identifier + example: 1 + in: path + name: meeting_id + required: true + schema: + type: integer + - description: Section identifier + example: 1 + in: path + name: id + required: true + schema: + type: integer + responses: + '200': + description: OK + content: + application/hal+json: + schema: + $ref: "../components/schemas/meeting_section_model.yml" + '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 requested resource could not be found. + description: |- + Returned if the section or meeting does not exist or the client does not have sufficient permissions. diff --git a/docs/api/apiv3/paths/meeting_sections.yml b/docs/api/apiv3/paths/meeting_sections.yml index 5d5bf04218a..db095f5071f 100644 --- a/docs/api/apiv3/paths/meeting_sections.yml +++ b/docs/api/apiv3/paths/meeting_sections.yml @@ -1,56 +1,11 @@ -# /api/v3/meetings/{id}/sections +# /api/v3/meeting_sections --- -get: - summary: List meeting sections - operationId: list_meeting_sections - tags: - - Meetings - description: Lists all sections for the given meeting. - parameters: - - description: Meeting identifier - example: 1 - in: path - name: id - required: true - schema: - type: integer - responses: - '200': - description: OK - content: - application/hal+json: - schema: - $ref: "../components/schemas/meeting_section_collection_model.yml" - '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 requested resource could not be found. - description: |- - Returned if the meeting does not exist or the client does not have sufficient permissions to see it. - - **Required permission:** view meetings - post: summary: Create meeting section operationId: create_meeting_section tags: - Meetings - description: Creates a new section for the given meeting. - parameters: - - description: Meeting identifier - example: 1 - in: path - name: id - required: true - schema: - type: integer + description: Creates a new section. The request body must link the meeting. requestBody: content: application/json: @@ -92,7 +47,7 @@ post: errorIdentifier: urn:openproject-org:api:v3:errors:NotFound message: The requested resource could not be found. description: |- - Returned if the meeting does not exist or the client does not have sufficient permissions to see it. + Returned if the linked meeting does not exist or the client does not have sufficient permissions to see it. '406': $ref: "../components/responses/missing_content_type.yml" '415': diff --git a/docs/api/apiv3/paths/meeting_sections_by_meeting.yml b/docs/api/apiv3/paths/meeting_sections_by_meeting.yml new file mode 100644 index 00000000000..e54b6956670 --- /dev/null +++ b/docs/api/apiv3/paths/meeting_sections_by_meeting.yml @@ -0,0 +1,38 @@ +# /api/v3/meetings/{id}/sections +--- +get: + summary: List meeting sections + operationId: list_meeting_sections + tags: + - Meetings + description: Lists all sections for the given meeting. + parameters: + - description: Meeting identifier + example: 1 + in: path + name: id + required: true + schema: + type: integer + responses: + '200': + description: OK + content: + application/hal+json: + schema: + $ref: "../components/schemas/meeting_section_collection_model.yml" + '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 requested resource could not be found. + description: |- + Returned if the meeting does not exist or the client does not have sufficient permissions to see it. + + **Required permission:** view meetings