OpenAPI documentation added
This commit is contained in:
Mal
parent
a42f728ccf
commit
44aaff929c
|
|
@ -0,0 +1,475 @@
|
|||
openapi: 3.0.0
|
||||
|
||||
info:
|
||||
title: Ringfinger API
|
||||
version: 1.0.0
|
||||
description: The restfull API of the jabber fingerprint keyring.
|
||||
|
||||
servers:
|
||||
- url: https://sabolli.de/ringfinger
|
||||
description: Test server
|
||||
|
||||
tags:
|
||||
- name: User
|
||||
description: A user that can login, store fingerprints and share them with other users.
|
||||
- name: Fingerprint
|
||||
description: The jabber fingerprint owned by a user.
|
||||
- name: Sharing
|
||||
description: The sharing of all fingerprints of a user with another user.
|
||||
|
||||
paths:
|
||||
'/api/v1/user/{userId}':
|
||||
get:
|
||||
tags:
|
||||
- User
|
||||
summary: Returns the user attributes
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/UserId'
|
||||
responses:
|
||||
200:
|
||||
description: Returns the user data for the given id.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
$ref: '#/components/schemas/Success'
|
||||
result:
|
||||
type: object
|
||||
description: Contains the user data.
|
||||
properties:
|
||||
userId:
|
||||
$ref: '#/components/schemas/UserId'
|
||||
usernamme:
|
||||
$ref: '#/components/schemas/Username'
|
||||
jabberAddress:
|
||||
$ref: '#/components/schemas/JabberAddress'
|
||||
fingerprintIds:
|
||||
type: array
|
||||
items:
|
||||
type: integer
|
||||
description: A list of all fingerprint ids of the user.
|
||||
example: [25, 42, 88]
|
||||
default: []
|
||||
default:
|
||||
$ref: '#/components/responses/Error'
|
||||
put:
|
||||
tags:
|
||||
- User
|
||||
summary: Changes user attributes
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/UserId'
|
||||
requestBody:
|
||||
required: true
|
||||
description: Contains the json with the user attributes that have to be changed.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
properties:
|
||||
username:
|
||||
$ref: '#/components/schemas/Username'
|
||||
password:
|
||||
$ref: '#/components/schemas/Password'
|
||||
email:
|
||||
$ref: '#/components/schemas/EmailAddress'
|
||||
jabberAddress:
|
||||
$ref: '#/components/schemas/JabberAddress'
|
||||
responses:
|
||||
200:
|
||||
$ref: '#/components/responses/Success'
|
||||
default:
|
||||
$ref: '#/components/responses/Error'
|
||||
delete:
|
||||
tags:
|
||||
- User
|
||||
summary: Deletes a user
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/UserId'
|
||||
responses:
|
||||
200:
|
||||
$ref: '#/components/responses/Success'
|
||||
default:
|
||||
$ref: '#/components/responses/Error'
|
||||
|
||||
'/api/v1/user':
|
||||
post:
|
||||
tags:
|
||||
- User
|
||||
summary: Creates a new user
|
||||
requestBody:
|
||||
required: true
|
||||
description: 'The attributes for the user to be created.'
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
properties:
|
||||
username:
|
||||
$ref: '#/components/schemas/Username'
|
||||
password:
|
||||
$ref: '#/components/schemas/Password'
|
||||
email:
|
||||
$ref: '#/components/schemas/EmailAddress'
|
||||
jabberAddress:
|
||||
$ref: '#/components/schemas/JabberAddress'
|
||||
allOf:
|
||||
- required:
|
||||
- username
|
||||
- password
|
||||
- email
|
||||
- jabberAddress
|
||||
responses:
|
||||
200:
|
||||
$ref: '#/components/responses/Success'
|
||||
default:
|
||||
$ref: '#/components/responses/Error'
|
||||
|
||||
'/api/v1/user/session':
|
||||
post:
|
||||
tags:
|
||||
- User
|
||||
summary: Creates a user session (login)
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
properties:
|
||||
username:
|
||||
$ref: '#/components/schemas/Username'
|
||||
password:
|
||||
$ref: '#/components/schemas/Password'
|
||||
allOf:
|
||||
- required:
|
||||
- username
|
||||
- password
|
||||
responses:
|
||||
200:
|
||||
description: Returns the success state and the user id for the created session.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
properties:
|
||||
success:
|
||||
$ref: '#/components/schemas/Success'
|
||||
userId:
|
||||
$ref: '#/components/schemas/UserId'
|
||||
default:
|
||||
$ref: '#/components/responses/Error'
|
||||
delete:
|
||||
tags:
|
||||
- User
|
||||
summary: Deletes a user session (logout)
|
||||
responses:
|
||||
200:
|
||||
$ref: '#/components/responses/Success'
|
||||
default:
|
||||
$ref: '#/components/responses/Error'
|
||||
|
||||
'/api/v1/fingerprint/{fingerprintId}/qr':
|
||||
get:
|
||||
tags:
|
||||
- Fingerprint
|
||||
summary: Returns the fingerprint's QR code
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/FingerprintId'
|
||||
responses:
|
||||
200:
|
||||
description: The QR code as SVG image
|
||||
content:
|
||||
application/svg+xml:
|
||||
schema:
|
||||
type: string
|
||||
description: The xml of the SVG image.
|
||||
default:
|
||||
$ref: '#/components/responses/Error'
|
||||
|
||||
'/api/v1/fingerprint/{fingerprintId}':
|
||||
get:
|
||||
tags:
|
||||
- Fingerprint
|
||||
summary: Returns the attributes of the fingerprint
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/FingerprintId'
|
||||
responses:
|
||||
200:
|
||||
description: Returns the fingerprint for the given fingerprint id.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
fingerprintId:
|
||||
$ref: '#/components/schemas/FingerprintId'
|
||||
fingerprint:
|
||||
$ref: '#/components/schemas/Fingerprint'
|
||||
userId:
|
||||
type: integer
|
||||
description: The id of the user that owns this fingerprint.
|
||||
example: 25
|
||||
default:
|
||||
$ref: '#/components/responses/Error'
|
||||
put:
|
||||
tags:
|
||||
- Fingerprint
|
||||
summary: Changes the fingerprint
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/FingerprintId'
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
properties:
|
||||
fingerprint:
|
||||
$ref: '#/components/schemas/Fingerprint'
|
||||
required:
|
||||
- fingerprint
|
||||
responses:
|
||||
200:
|
||||
description: Returns the success state.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
description: 'Returns the success state of the fingerprint change.'
|
||||
example: true
|
||||
message:
|
||||
type: string
|
||||
description: 'Returns if no changes have been found inside the request body.'
|
||||
example: 'Fingerprint did not differ from the stored. Nothing changed.'
|
||||
required:
|
||||
- success
|
||||
default:
|
||||
$ref: '#/components/responses/Error'
|
||||
|
||||
delete:
|
||||
tags:
|
||||
- Fingerprint
|
||||
summary: Removes the fingerprint
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/FingerprintId'
|
||||
responses:
|
||||
200:
|
||||
$ref: '#/components/responses/Success'
|
||||
default:
|
||||
$ref: '#/components/responses/Error'
|
||||
|
||||
'/api/v1/fingerprint':
|
||||
post:
|
||||
tags:
|
||||
- Fingerprint
|
||||
summary: Creates a new fingerprint
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
description: The parameters for the new fingerprint to be created.
|
||||
properties:
|
||||
fingerprint:
|
||||
$ref: '#/components/schemas/Fingerprint'
|
||||
userId:
|
||||
$ref: '#/components/schemas/UserId'
|
||||
required:
|
||||
- fingerprint
|
||||
- userId
|
||||
|
||||
responses:
|
||||
200:
|
||||
description: Returns the confirmation and the id for the newly created fingerprint.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
description: Returns the success status.
|
||||
example: true
|
||||
fingerprintId:
|
||||
type: integer
|
||||
description: The id for the newly created fingerprint.
|
||||
example: 42
|
||||
default:
|
||||
$ref: '#/components/responses/Error'
|
||||
|
||||
'/api/v1/sharing/{sharingId}':
|
||||
get:
|
||||
tags:
|
||||
- Sharing
|
||||
summary: Returns the sharing attributes
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/SharingId'
|
||||
responses:
|
||||
200:
|
||||
description: The JSON result for the sharing.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
properties:
|
||||
success:
|
||||
$ref: '#/components/schemas/Success'
|
||||
result:
|
||||
type: object
|
||||
properties:
|
||||
sharingId:
|
||||
$ref: '#/components/schemas/SharingId'
|
||||
userId:
|
||||
type: integer
|
||||
description: The id of the user that shares his fingerprints.
|
||||
example: 42
|
||||
userSharedId:
|
||||
$ref: '#/components/schemas/SharingUserId'
|
||||
default:
|
||||
$ref: '#/components/responses/Error'
|
||||
delete:
|
||||
tags:
|
||||
- Sharing
|
||||
summary: Removes the specified sharing
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/SharingId'
|
||||
responses:
|
||||
200:
|
||||
$ref: '#/components/responses/Success'
|
||||
default:
|
||||
$ref: '#/components/responses/Error'
|
||||
|
||||
'/api/v1/sharing':
|
||||
post:
|
||||
tags:
|
||||
- Sharing
|
||||
summary: Creates a new sharing
|
||||
requestBody:
|
||||
description: Contains the attributes for the sharing to be created.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
userId:
|
||||
type: integer
|
||||
description: The id of the user that shares his fingerprints.
|
||||
example: 42
|
||||
userSharedId:
|
||||
$ref: '#/components/schemas/SharingUserId'
|
||||
|
||||
responses:
|
||||
200:
|
||||
description: Returns the success flag and the id for the newly created sharing.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
$ref: '#/components/schemas/Success'
|
||||
sharingId:
|
||||
$ref: '#/components/schemas/SharingId'
|
||||
default:
|
||||
$ref: '#/components/responses/Error'
|
||||
|
||||
components:
|
||||
parameters:
|
||||
FingerprintId:
|
||||
name: fingerprintId
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/components/schemas/FingerprintId'
|
||||
|
||||
SharingId:
|
||||
name: sharingId
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/components/schemas/SharingId'
|
||||
|
||||
UserId:
|
||||
name: userId
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/components/schemas/UserId'
|
||||
|
||||
responses:
|
||||
Success:
|
||||
description: Returns that the request could be handled successfully.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
properties:
|
||||
success:
|
||||
$ref: '#/components/schemas/Success'
|
||||
|
||||
Error:
|
||||
description: Returns a JSON object that describes the error.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
|
||||
schemas:
|
||||
Error:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
description: Returns that the request couldn't be handled.
|
||||
example: false
|
||||
message:
|
||||
type: string
|
||||
description: Description of the error that occured.
|
||||
example: Something extremely terrible happened!
|
||||
|
||||
Success:
|
||||
type: boolean
|
||||
description: Returns if the request could be handled.
|
||||
example: true
|
||||
|
||||
UserId:
|
||||
type: integer
|
||||
description: The id of the user in question.
|
||||
example: 42
|
||||
|
||||
Username:
|
||||
type: string
|
||||
description: The login name for the given user.
|
||||
example: Kevin42
|
||||
|
||||
Password:
|
||||
type: string
|
||||
description: The password for the user login.
|
||||
example: '12345'
|
||||
|
||||
JabberAddress:
|
||||
type: string
|
||||
description: The address of the jabber account.
|
||||
example: donalt@jabber.de
|
||||
|
||||
EmailAddress:
|
||||
type: string
|
||||
description: The registered email address for the user.
|
||||
example: kevin@gmail.com
|
||||
|
||||
FingerprintId:
|
||||
type: integer
|
||||
description: The id that identifies the fingerprint.
|
||||
example: 42
|
||||
readOnly: true
|
||||
|
||||
Fingerprint:
|
||||
type: string
|
||||
description: The jabber fingerprint
|
||||
example: '5BDF1668E59F2184582591699F55D9158DEF400A48772887A8F61531ED36B2A'
|
||||
|
||||
SharingId:
|
||||
type: integer
|
||||
description: The id for the sharing.
|
||||
example: 42
|
||||
readOnly: true
|
||||
|
||||
SharingUserId:
|
||||
type: integer
|
||||
description: The id of the user who is allowed to display the fingerprints.
|
||||
example: 25
|
||||
Loading…
Reference in New Issue