Update openapi docs

This commit is contained in:
Oliver Günther
2026-06-08 12:59:10 +02:00
parent 164e31c1d5
commit ccdaa9f534
13 changed files with 378 additions and 420 deletions
+14 -2
View File
@@ -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"
+5 -50
View File
@@ -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.
@@ -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.
@@ -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.
@@ -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`)
+3 -48
View File
@@ -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':
@@ -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
+124
View File
@@ -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.
+59
View File
@@ -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`)
+7 -58
View File
@@ -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.
@@ -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.
+3 -48
View File
@@ -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':
@@ -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