dschick/git_brcal
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improved OpenAPI doc in Stoplight, but still issues with ParticipantType and nullable Types. The client code does not compile.

Browse Source
This commit is contained in:
Daniel Schick 2023-12-15 15:57:12 +01:00
parent c6b16c4fa7
commit 5459d99098
2 changed files with 2501 additions and 1928 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2680
misc/BreCalApi.cs
View File

File diff suppressed because it is too large Load Diff

565
misc/BreCalApi.yaml
View File

@ -1,329 +1,381 @@
openapi: "3.1.0" openapi: 3.1.0
x-stoplight:
id: iucm9tq7jgu7j
info: info:
version: "1.1.0" version: 1.1.0
title: "Bremen calling API" title: Bremen calling API
description: Administer DEBRE ship calls, times and notifications description: 'Administer DEBRE ship calls, times and notifications'
termsOfService: "https://www.bsmd.de/" # TBD: url to terms page termsOfService: 'https://www.bsmd.de/'
contact: contact:
name: "Bremen calling API" name: Bremen calling API
url: "https://www.textbausteine.net" url: 'https://www.textbausteine.net'
email: "info@textbausteine.net" email: info@textbausteine.net
license: license:
name: "Use at your own risk" name: Use at your own risk
url: "https://www.bsmd.de/license" url: 'https://www.bsmd.de/license'
summary: Bremen calling
servers: servers:
- url: "https://brecaldevel.bsmd-emswe.eu/" - url: 'https://brecaldevel.bsmd-emswe.eu'
description: "Development server hosted on vcup" description: Development server hosted on vcup
tags:
- name: user
- name: shipcall
- name: times
- name: static
paths: paths:
/login: /login:
post: post:
description: Perform login
summary: Returns a JWT session token and user data if successful summary: Returns a JWT session token and user data if successful
tags:
- user
operationId: login
requestBody: requestBody:
description: Login credentials description: Login credentials
required: true required: true
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/credentials" $ref: '#/components/schemas/credentials'
responses: responses:
200: '200':
description: Successful response description: Successful response
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/login_result" $ref: '#/components/schemas/login_result'
400: '400':
$ref: "#/components/responses/400" $ref: '#/components/responses/400'
403: '403':
$ref: "#/components/responses/403" $ref: '#/components/responses/403'
500: '500':
$ref: "#/components/responses/500" $ref: '#/components/responses/500'
503: '503':
$ref: "#/components/responses/503" $ref: '#/components/responses/503'
/user: /user:
put: put:
summary: Update user details (first/last name, phone, password) description: Update user information
summary: 'Update user details (first/last name, phone, password)'
tags:
- user
operationId: userUpdate
requestBody: requestBody:
description: User details description: User details
required: true required: true
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/user_details" $ref: '#/components/schemas/user_details'
responses: responses:
400: '200':
$ref: "#/components/responses/400" $ref: '#/components/responses/200'
401: '400':
$ref: "#/components/responses/401" $ref: '#/components/responses/400'
500: '401':
$ref: "#/components/responses/500" $ref: '#/components/responses/401'
503: '500':
$ref: "#/components/responses/503" $ref: '#/components/responses/500'
'503':
$ref: '#/components/responses/503'
/shipcalls: /shipcalls:
get: get:
description: Get current ship calls
summary: Gets a list of ship calls summary: Gets a list of ship calls
tags:
- shipcall
operationId: shipcallsGet
parameters: parameters:
- name: past_days - name: past_days
in: query in: query
required: false required: false
description: "number of days in the past to include in the result. *Example: 7*." description: 'number of days in the past to include in the result. *Example: 7*.'
schema: schema:
type: integer type: integer
responses: responses:
200: '200':
description: ship call list description: ship call list
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/shipcalls" $ref: '#/components/schemas/shipcalls'
400: '400':
$ref: "#/components/responses/400" $ref: '#/components/responses/400'
401: '401':
$ref: "#/components/responses/401" $ref: '#/components/responses/401'
500: '500':
$ref: "#/components/responses/500" $ref: '#/components/responses/500'
503: '503':
$ref: "#/components/responses/503" $ref: '#/components/responses/503'
post: post:
summary: Create a new ship call summary: Create a new ship call
description: A new shipcall is created without times at this point. This is ususally done by the BSMD or a participant with that particular role.
tags:
- shipcall
operationId: shipcallCreate
requestBody: requestBody:
description: Creates a new ship call. **Do not** provide id parameter. description: Creates a new ship call. **Do not** provide id parameter.
required: true required: true
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/shipcall" $ref: '#/components/schemas/shipcall'
responses: responses:
201: '201':
$ref: "#/components/responses/201" $ref: '#/components/responses/201'
400: '400':
$ref: "#/components/responses/400" $ref: '#/components/responses/400'
401: '401':
$ref: "#/components/responses/401" $ref: '#/components/responses/401'
500: '500':
$ref: "#/components/responses/500" $ref: '#/components/responses/500'
503: '503':
$ref: "#/components/responses/503" $ref: '#/components/responses/503'
put: put:
summary: Updates a ship call summary: Updates a ship call
description: Updates a shipcall. Usually done if the participant assignments change.
tags:
- shipcall
operationId: shipcallUpdate
requestBody: requestBody:
description: Creates a new ship call. The id parameter is **required**. description: Creates a new ship call. The id parameter is **required**.
required: true required: true
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/shipcall" $ref: '#/components/schemas/shipcall'
responses: responses:
200: '200':
$ref: "#/components/responses/200" $ref: '#/components/responses/200'
400: '400':
$ref: "#/components/responses/400" $ref: '#/components/responses/400'
401: '401':
$ref: "#/components/responses/401" $ref: '#/components/responses/401'
500: '500':
$ref: "#/components/responses/500" $ref: '#/components/responses/500'
503: '503':
$ref: "#/components/responses/503" $ref: '#/components/responses/503'
/ships: /ships:
get: get:
summary: gets a list of registered shipcalls summary: gets a list of ships
description: Gets a list of ships including logically deleted ships to be used with shipcalls
tags:
- static
operationId: shipsGet
responses: responses:
200: '200':
description: list of ships description: list of ships
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/ship_list" $ref: '#/components/schemas/ship_list'
400: '400':
$ref: "#/components/responses/400" $ref: '#/components/responses/400'
401: '401':
$ref: "#/components/responses/401" $ref: '#/components/responses/401'
500: '500':
$ref: "#/components/responses/500" $ref: '#/components/responses/500'
503: '503':
$ref: "#/components/responses/503" $ref: '#/components/responses/503'
/participants: /participants:
get: get:
summary: gets a particular participant entry corresponding to user id summary: gets one or all participants
description: 'If no parameter is given, all participants are returned. The list can be used to display participant information in the context of ship calls.'
tags:
- static
operationId: participantsGet
parameters: parameters:
- name: user_id - name: user_id
in: query in: query
required: false required: false
description: "**Id of user**. *Example: 2*. User id returned by verify call." description: '**Id of user**. *Example: 2*. User id returned by verify call.'
schema: schema:
type: integer type: integer
responses: responses:
200: '200':
description: ship call list description: ship call list
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/participant_list" $ref: '#/components/schemas/participant_list'
400: '400':
$ref: "#/components/responses/400" $ref: '#/components/responses/400'
404: '401':
$ref: "#/components/responses/404" $ref: '#/components/responses/401'
401: '404':
$ref: "#/components/responses/401" $ref: '#/components/responses/404'
500: '500':
$ref: "#/components/responses/500" $ref: '#/components/responses/500'
503: '503':
$ref: "#/components/responses/503" $ref: '#/components/responses/503'
/times: /times:
get: get:
summary: Get all recorded times for a a ship call summary: Gets list of times
description: Get all times assigned to a shipcall. These might not be complete.
tags:
- times
operationId: timesGet
parameters: parameters:
- name: shipcall_id - name: shipcall_id
in: query in: query
description: "**Id**. *Example: 42*. Id of referenced ship call." description: '**Id**. *Example: 42*. Id of referenced ship call.'
schema: schema:
type: integer type: integer
responses: responses:
200: '200':
description: list of recorded times description: list of recorded times
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/times_list" $ref: '#/components/schemas/times_list'
400: '400':
$ref: "#/components/responses/400" $ref: '#/components/responses/400'
401: '401':
$ref: "#/components/responses/401" $ref: '#/components/responses/401'
500: '500':
$ref: "#/components/responses/500" $ref: '#/components/responses/500'
503: '503':
$ref: "#/components/responses/503" $ref: '#/components/responses/503'
post: post:
summary: Create a new times entry for a ship call summary: Create a new times entry for a ship call
description: The times entry for a shipcall is created with reference to a participant. For each participant type there should be only one times data record.
tags:
- times
operationId: timesCreate
requestBody: requestBody:
description: Times entry that will be added to the ship call. **Do not** provide id parameter. description: Times entry that will be added to the ship call. **Do not** provide id parameter.
required: true required: true
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/times" $ref: '#/components/schemas/times'
responses: responses:
201: '201':
$ref: "#/components/responses/201" $ref: '#/components/responses/201'
400: '400':
$ref: "#/components/responses/400" $ref: '#/components/responses/400'
401: '401':
$ref: "#/components/responses/401" $ref: '#/components/responses/401'
500: '500':
$ref: "#/components/responses/500" $ref: '#/components/responses/500'
503: '503':
$ref: "#/components/responses/503" $ref: '#/components/responses/503'
put: put:
summary: Update a times entry for a ship call summary: Update a times entry for a ship call
description: Updating a times entry for a ship for a particular participant. The times entries are required for a shipcall to pass the validation rules.
tags:
- times
operationId: timesUpdate
requestBody: requestBody:
description: Times entry that will be added to the ship call. The id parameter is **required**. description: Times entry that will be added to the ship call. The id parameter is **required**.
required: true required: true
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/times" $ref: '#/components/schemas/times'
responses: responses:
200: '200':
$ref: "#/components/responses/200" $ref: '#/components/responses/200'
400: '400':
$ref: "#/components/responses/400" $ref: '#/components/responses/400'
401: '401':
$ref: "#/components/responses/401" $ref: '#/components/responses/401'
500: '500':
$ref: "#/components/responses/500" $ref: '#/components/responses/500'
503: '503':
$ref: "#/components/responses/503" $ref: '#/components/responses/503'
delete: delete:
summary: Delete a times entry for a ship call. summary: Delete a times entry for a ship call.
description: A times entry is typically deleted if the agent for example changes or removes the participant assignment for a particular role.
tags:
- times
operationId: timesDelete
parameters: parameters:
- name: id - name: id
in: query in: query
required: true required: true
schema: schema:
$ref: "#/components/schemas/timesId" $ref: '#/components/schemas/timesId'
responses: responses:
400: '200':
$ref: "#/components/responses/400" $ref: '#/components/responses/200'
401: '400':
$ref: "#/components/responses/401" $ref: '#/components/responses/400'
500: '401':
$ref: "#/components/responses/500" $ref: '#/components/responses/401'
503: '500':
$ref: "#/components/responses/503" $ref: '#/components/responses/500'
'503':
$ref: '#/components/responses/503'
/notifications: /notifications:
get: get:
summary: Gets a list of notifications pursuant to a specified participant and ship call summary: Gets a list of notifications pursuant to a specified participant and ship call
description: List of notifications (tbd)
tags:
- static
operationId: notificationsGet
parameters: parameters:
- name: participant_id - name: participant_id
in: query in: query
required: true required: true
description: "**Id of participant**. *Example: 2*. Id returned through loading of participant" description: '**Id of participant**. *Example: 2*. Id returned through loading of participant'
schema: schema:
type: integer type: integer
- name: shipcall_id - name: shipcall_id
in: query in: query
required: true required: true
description: "**Id of ship call**. *Example: 52*. Id given in ship call list" description: '**Id of ship call**. *Example: 52*. Id given in ship call list'
schema: schema:
$ref: "#/components/schemas/shipcallId" $ref: '#/components/schemas/shipcallId'
responses: responses:
200: '200':
description: notification list description: notification list
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/notification" $ref: '#/components/schemas/notification'
400: '400':
$ref: "#/components/responses/400" $ref: '#/components/responses/400'
401: '401':
$ref: "#/components/responses/401" $ref: '#/components/responses/401'
500: '500':
$ref: "#/components/responses/500" $ref: '#/components/responses/500'
503: '503':
$ref: "#/components/responses/503" $ref: '#/components/responses/503'
/berths: /berths:
get: get:
description: 'Returns a list of berths, including berths that are (logically) deleted'
summary: Gets a list of all berths registered summary: Gets a list of all berths registered
tags:
- static
operationId: berthsGet
responses: responses:
200: '200':
description: list of berths description: list of berths
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/berth_list" $ref: '#/components/schemas/berth_list'
400: '400':
$ref: "#/components/responses/400" $ref: '#/components/responses/400'
401: '401':
$ref: "#/components/responses/401" $ref: '#/components/responses/401'
500: '500':
$ref: "#/components/responses/500" $ref: '#/components/responses/500'
503: '503':
$ref: "#/components/responses/503" $ref: '#/components/responses/503'
components: components:
schemas: schemas:
credentials: credentials:
type: object type: object
required:
- username
- password
properties: properties:
username: username:
type: string type: string
password: password:
type: string type: string
format: password format: password
required:
- username
- password
timesId: timesId:
description: The unique identifier for a times entry description: The unique identifier for a times entry
type: integer type: integer
@ -349,11 +401,11 @@ components:
- type - type
properties: properties:
id: id:
$ref: "#/components/schemas/shipcallId" $ref: '#/components/schemas/shipcallId'
ship_id: ship_id:
type: integer type: integer
type: type:
type: ShipcallType $ref: '#/components/schemas/ShipcallType'
eta: eta:
type: string type: string
format: date-time format: date-time
@ -429,7 +481,7 @@ components:
participants: participants:
type: array type: array
items: items:
$ref: "#/components/schemas/participant_assignment" $ref: '#/components/schemas/participant_assignment'
created: created:
type: string type: string
format: date-time format: date-time
@ -437,15 +489,13 @@ components:
type: string type: string
format: date-time format: date-time
nullable: true nullable: true
shipcalls: shipcalls:
type: array type: array
items: items:
$ref: "#/components/schemas/shipcall" $ref: '#/components/schemas/shipcall'
times: times:
type: object type: object
description: the id parameter needs to be missing on POST and to be present on PUT (Update) calls, otherwise a 400 response will be generated description: 'the id parameter needs to be missing on POST and to be present on PUT (Update) calls, otherwise a 400 response will be generated'
required: required:
- shipcall_id - shipcall_id
- participant_id - participant_id
@ -506,7 +556,7 @@ components:
type: boolean type: boolean
nullable: true nullable: true
participant_type: participant_type:
type: ParticipantType $ref: '#/components/schemas/ParticipantType2'
created: created:
type: string type: string
format: date-time format: date-time
@ -514,12 +564,10 @@ components:
type: string type: string
format: date-time format: date-time
nullable: true nullable: true
times_list: times_list:
type: array type: array
items: items:
$ref: "#/components/schemas/times" $ref: '#/components/schemas/times'
berth: berth:
type: object type: object
description: Ship berth used for a ship call description: Ship berth used for a ship call
@ -548,12 +596,10 @@ components:
deleted: deleted:
type: boolean type: boolean
default: false default: false
berth_list: berth_list:
type: array type: array
items: items:
$ref: "#/components/schemas/berth" $ref: '#/components/schemas/berth'
ship: ship:
type: object type: object
description: a ship description: a ship
@ -600,12 +646,10 @@ components:
deleted: deleted:
type: boolean type: boolean
default: false default: false
ship_list: ship_list:
type: array type: array
items: items:
$ref: "#/components/schemas/ship" $ref: '#/components/schemas/ship'
notification: notification:
type: object type: object
description: a notification created by the engine if a times entry violates a rule description: a notification created by the engine if a times entry violates a rule
@ -617,7 +661,7 @@ components:
participant_id: participant_id:
type: integer type: integer
notification_type: notification_type:
$ref: "#/components/schemas/NotificationType" $ref: '#/components/schemas/NotificationType'
timestamp: timestamp:
type: string type: string
format: date-time format: date-time
@ -630,12 +674,6 @@ components:
type: string type: string
format: date-time format: date-time
nullable: true nullable: true
notification_list:
type: array
items:
$ref: "#/components/schemas/notification"
participant: participant:
type: object type: object
description: A organisational entity that participates in Bremen Calling description: A organisational entity that participates in Bremen Calling
@ -655,7 +693,8 @@ components:
type: string type: string
maxLength: 64 maxLength: 64
type: type:
type: ParticipantType type: integer
description: a logical combinat
flags: flags:
type: integer type: integer
nullable: true nullable: true
@ -669,12 +708,10 @@ components:
deleted: deleted:
type: boolean type: boolean
default: false default: false
participant_list: participant_list:
type: array type: array
items: items:
$ref: "#/components/schemas/participant" $ref: '#/components/schemas/participant'
login_result: login_result:
type: object type: object
description: result structure of a successful login attempt description: result structure of a successful login attempt
@ -698,7 +735,6 @@ components:
format: float format: float
token: token:
type: string type: string
user_details: user_details:
type: object type: object
description: fields that a user may change description: fields that a user may change
@ -737,15 +773,21 @@ components:
message: message:
description: A human readable error message description: A human readable error message
type: string type: string
ShipcallType: ShipcallType:
type: string type: string
enum: [undefined, arrival, departure, shifting] enum:
- undefined
- arrival
- departure
- shifting
x-internal: false
description: ''
NotificationType: NotificationType:
type: string type: string
enum: [undefined, email, push] enum:
- undefined
- email
- push
ParticipantType: ParticipantType:
type: integer type: integer
enum: enum:
@ -757,103 +799,98 @@ components:
- 32 - 32
- 64 - 64
x-enumDescriptions: x-enumDescriptions:
1: bsmd '1': bsmd
2: terminal '2': terminal
4: pilot '4': pilot
8: agency '8': agency
16: mooring '16': mooring
32: port_authority '32': port_authority
64: tug '64': tug
ParticipantType2:
# this here works only with OpenAPI 3.1 title: ParticipantType2
# ParticipantType: x-stoplight:
# type: integer id: whw0m8x8dq6cg
# oneOf: type: integer
# - const: 1 oneOf:
# title: bsmd - const: 1
# description: Bremen Schiffsmeldedienst title: bsmd
description: Bremen Schiffsmeldedienst
# - const: 2 - const: 2
# title: terminal title: terminal
# description: Terminal description: Terminal
- const: 4
# - const: 4 title: pilot
# title: pilot description: Pilot
# description: Pilot - const: 8
title: agency
# - const: 8 description: Agency
# title: agency - const: 16
# description: Agency title: mooring
description: Mooring
# - const: 16 - const: 32
# title: mooring title: port_authority
# description: Mooring description: Port Authority
- const: 64
# - const: 32 title: tug
# title: port_authority description: Tug
# description: Port Authority description: Enumeration that can take particular values
# - const: 64
# title: tug
# description: Tug
securitySchemes: securitySchemes:
ApiKey: ApiKey:
type: apiKey type: apiKey
in: header in: header
name: Authorization name: Authorization
responses: responses:
200: '200':
description: OK description: OK
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/Id" $ref: '#/components/schemas/Id'
201: '201':
description: Created description: Created
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/Id" $ref: '#/components/schemas/Id'
400: '400':
description: Bad request description: Bad request
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/Error" $ref: '#/components/schemas/Error'
401: '401':
description: Not authorized description: Not authorized
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/Error" $ref: '#/components/schemas/Error'
403: '403':
description: Forbidden description: Forbidden
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/Error" $ref: '#/components/schemas/Error'
404: '404':
description: Not found description: Not found
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/Error" $ref: '#/components/schemas/Error'
500: '500':
description: Unexpected error description: Unexpected error
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/Error" $ref: '#/components/schemas/Error'
503: '503':
description: Service unavailable description: Service unavailable
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/Error" $ref: '#/components/schemas/Error'
security: security:
- ApiKey: [] - ApiKey: []
externalDocs: externalDocs:
url: http://textbausteine.net/ url: 'http://textbausteine.net/'
description: Extra documentation and conditions for Bremen Calling description: Extra documentation and conditions for Bremen Calling
x-internal: true