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

added OpenApi description 

Signed-off-by: Stephan Richter <s.richter@srsoftware.de>
main
Stephan Richter 4 months ago
parent
3c36274b02
commit
10ad309d8c
1 changed files with 337 additions and 0 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 337
      doc/openapi3_0.yaml

337
doc/openapi3_0.yaml
Unescape 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
Write Preview
Loading…
Cancel
Save