SRSoftware/OpenCloudCal
1
0
Fork 0
Code Issues Pull Requests Actions Projects Releases Wiki Activity

added OpenApi description

Browse Source 
Signed-off-by: Stephan Richter <s.richter@srsoftware.de>
This commit is contained in:
Stephan Richter
2024-12-30 12:19:38 +01:00
parent 3c36274b02
commit 10ad309d8c
1 changed files with 337 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

337
doc/openapi3_0.yaml Normal file
View File

@@ -0,0 +1,337 @@
openapi: 3.0.3
info:
title: OpenCloucCal API
description: |-
The OpenCloucCal API describes the Backend of the OpenCloudCal webservice,
which is both used for the frontend and may also
be used for third-party services
license:
name: MIT license
url: https://git.srsoftware/REPO/License.md
version: 1.0.0
servers:
- url: https://cal.srsoftware.de
- url: http://localhost:8080
paths:
/api/events/json:
get:
description: |-
Get a list of events from the server in JSON format.
Filters may be applied by using request parameters.
parameters:
- description: Filter keywords. Only events having all provided tags are listed
example: magrathea,heartofgold
in: query
name: tags
required: false
schema:
format: comma-separated values
type: string
- description: start time. Only events after this date time are returned
example: 2024-12-30T10:32
in: query
name: start
required: false
schema:
format: date-time
type: string
- description: |-
Return past events, if set. Allowed values:
* all → return all events
* [n]m – return events including the last n months
* [n]y - return events including the last n years
example: 2m
in: query
name: past
required: false
schema:
type: string
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/AppointmentList'
'400':
description: invalid input
'500':
description: server fault
summary: Fetch event list
/api/events/ical:
get:
description: |-
Get a list of events from the server in ICAL format.
Filters may be applied by using request parameters.
parameters:
- description: Filter keywords. Only events having all provided tags are listed
example: magrathea,heartofgold
in: query
name: tags
required: false
schema:
format: comma-separated values
type: string
- description: start time. Only events after this date time are returned
example: 2024-12-30T10:32
in: query
name: start
required: false
schema:
format: date-time
type: string
- description: |-
Return past events, if set. Allowed values:
* all → return all events
* [n]m – return events including the last n months
* [n]y - return events including the last n years
example: 2m
in: query
name: past
required: false
schema:
type: string
responses:
'200':
description: successful operation
content:
text/calendar:
schema:
description: event list in ical format
example: |-
BEGIN:VCALENDAR
VERSION:2.0
PRODID:OpenCloudCal
BEGIN:VEVENT
UID:42@cal.srsoftware.de
DTSTART:20241230T100757Z
DTEND:20241231T100757Z
SUMMARY:Demolition of the earth
END:VEVENT
END:VCALENDAR
type: string
'400':
description: invalid input
'500':
description: server fault
summary: Fetch event list
/api/event:
delete:
description: Deletes the specified element from the list of events.
parameters:
- description: the appointment id
in: query
name: id
required: true
schema:
example: 42
format: int64
type: number
- description: title of the event as kind of confirmation
in: header
name: title
required: true
schema:
example: this will not confirm
format: string
responses:
'200':
description: successfull operation
'404':
description: invalid id (no such event)
'412':
description: mismatching title (no confirmation)
'500':
description: server fault
summary: remove an event
get:
parameters:
- description: the appointment id
in: query
name: id
required: true
schema:
example: 42
format: int64
type: number
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/AppointmentList'
'400':
description: invalid input
'500':
description: server fault
summary: get an event with all details
patch:
parameters:
- description: copy of the title
in: header
name: title
schema:
example: Demolition of the earth
type: string
requestBody:
description: update an appointment.
content:
application/json:
schema:
$ref: '#/components/schemas/AppointmentList'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/AppointmentList'
'400':
description: invalid input
'500':
description: server fault
summary: update the specified event
post:
parameters:
- description: copy of the title
in: header
name: title
schema:
example: Demolition of the earth
type: string
requestBody:
description: Create a new appointment. Id must be set to 0 (number zero).
content:
application/json:
schema:
$ref: '#/components/schemas/AppointmentList'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/AppointmentList'
'400':
description: invalid input
'500':
description: server fault
summary: store a new event in the database
components:
schemas:
Appointment:
description: an Event
type: object
properties:
id:
description: unique identifier of the appointment
example: 42
format: int64
type: number
title:
description: summary of the item
example: Demolition of the earth
type: string
description:
description: a text describing the event
example: Have your towel ready!
type: string
start:
description: date time when the event is scheduled to begin
format: date-time
type: string
end:
description: date time when the event is scheduled to end
format: date-time
type: string
location:
description: text describing the location of the event, i.e. address
example: Cottingto
type: string
coords:
$ref: '#/components/schemas/Coords'
attachments:
items:
$ref: '#/components/schemas/Attachment'
type: array
links:
description: list of links to content related to the event
items:
$ref: '#/components/schemas/Link'
type: array
tags:
description: keywords that describe the event. may be used to filter events
example:
- DouglasAdams
- Hitchhiker
- Guide
- Galaxy
items:
type: string
type: array
required:
- id
- location
- start
- title
AppointmentList:
description: list of appointments
type: array
items:
$ref: '#/components/schemas/Appointment'
Attachment:
description: |-
A link to a file additional information related to the event.
May be used for images, pdfs or anything apart from links to other websites.
type: object
properties:
mime:
description: MIME type of the attachment
type: string
example: image/png
url:
description: attachment URL
example: https://example.com/some/image.png
format: url
type: string
Coords:
description: location of the event site in a global coordinate system (WGS84)
type: object
properties:
latitude:
example: 11.5928
format: float
type: number
longitude:
example: 50.731
format: float
type: number
Ical:
description: event list in ical format
example: |-
BEGIN:VCALENDAR
VERSION:2.0
PRODID:OpenCloudCal
BEGIN:VEVENT
UID:42@cal.srsoftware.de
DTSTART:20241230T100757Z
DTEND:20241231T100757Z
SUMMARY:Demolition of the earth
END:VEVENT
END:VCALENDAR
type: string
Link:
description: hyperlink to content related to an event
properties:
description:
description: text describing the link target
example: Wikipedia article
type: string
url:
description: the target of the link
example: https://en.wikipedia.org/wiki/The_Hitchhiker's_Guide_to_the_Galaxy
type: string