added OpenApi description
Signed-off-by: Stephan Richter <s.richter@srsoftware.de>
This commit is contained in:
337
doc/openapi3_0.yaml
Normal file
337
doc/openapi3_0.yaml
Normal 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
|
||||
Reference in New Issue
Block a user