wasa-test/doc/api.yaml
2024-10-01 23:55:57 +02:00

273 lines
8.3 KiB
YAML

openapi: 3.0.0
servers:
- url: "http://localhost:3000"
info:
title: Fantastic Coffee (decaffeinated)
description: Fantastic Coffee (decaffeinated), the skeleton project for Web and Software architecture course
version: 1.0.0
paths:
/status:
parameters:
- $ref: "#/components/parameters/XAppBuild"
- $ref: "#/components/parameters/XAppVersion"
- $ref: "#/components/parameters/XAppLanguage"
- $ref: "#/components/parameters/XAppPlatform"
get:
tags: ["General"]
operationId: getStatusMessage
summary: Get status message for the user about issues / updates
description: |-
The response contains a status message meant for the user. It might
contains information about current technical issues, update messages
or general information.
responses:
"200":
description: Status message available
content:
application/json:
schema:
$ref: "#/components/schemas/StatusInfo"
"400": { $ref: "#/components/responses/BadRequest" }
"500": { $ref: "#/components/responses/InternalServerError" }
/:
get:
tags: ["Group 1"]
operationId: index
summary: Get an index
description: |-
This is an example of an index API description
responses:
"200":
description: Successful
"400": { $ref: "#/components/responses/BadRequest" }
"500": { $ref: "#/components/responses/InternalServerError" }
/context:
parameters:
- $ref: "#/components/parameters/XAppBuild"
- $ref: "#/components/parameters/XAppVersion"
- $ref: "#/components/parameters/XAppLanguage"
- $ref: "#/components/parameters/XAppPlatform"
post:
tags: ["Group 1"]
operationId: getContext
summary: Another API example
description: |-
Example description 2
responses:
"200":
description: Request ok
headers:
X-Access-Token:
description: Access token for authenticated requests
schema: { type: string }
"500": { $ref: "#/components/responses/InternalServerError" }
/authenticated:
parameters:
- $ref: "#/components/parameters/XAppBuild"
- $ref: "#/components/parameters/XAppVersion"
- $ref: "#/components/parameters/XAppLanguage"
- $ref: "#/components/parameters/XAppPlatform"
get:
tags: ["Group 2"]
operationId: getAuthenticatedExample
summary: Get an endpoint with authentication
description: |-
Get an endpoint with auth
security:
- LegacyAuth: []
- AppToken: []
responses:
"200":
description: Logout successful
"500": { $ref: "#/components/responses/InternalServerError" }
/pictures/{cat}:
parameters:
- $ref: "#/components/parameters/XAppBuild"
- $ref: "#/components/parameters/XAppVersion"
- $ref: "#/components/parameters/XAppLanguage"
- $ref: "#/components/parameters/XAppPlatform"
- $ref: "#/components/parameters/cat"
get:
tags: ["Cat pictures"]
operationId: getCatFromPicture
summary: Example of a parameter in URL
description: |-
Example of a parameter in URL
security:
- LegacyAuth: []
responses:
"200":
description: Student picture found
content:
image/png:
schema:
type: string
format: binary
example: Picture binary file
"404":
description: Student picture not found
"500": { $ref: "#/components/responses/InternalServerError" }
/autofeeder/{cat}:
parameters:
- $ref: "#/components/parameters/XAppBuild"
- $ref: "#/components/parameters/XAppVersion"
- $ref: "#/components/parameters/XAppLanguage"
- $ref: "#/components/parameters/XAppPlatform"
- $ref: "#/components/parameters/cat"
put:
tags: ["Autofeeder"]
operationId: createCatAutofeeder
summary: Example of PUT operation
security:
- LegacyAuth: []
responses:
"200":
description: Auto feed enabled
"400": { $ref: "#/components/responses/BadRequest" }
"500": { $ref: "#/components/responses/InternalServerError" }
delete:
tags: ["Autofeeder"]
operationId: deleteCatAutofeeder
summary: Example of DELETE operation
security:
- LegacyAuth: []
responses:
"200":
description: Auto feed disabled
"400": { $ref: "#/components/responses/BadRequest" }
"500": { $ref: "#/components/responses/InternalServerError" }
/session/login:
parameters:
- $ref: "#/components/parameters/XAppBuild"
- $ref: "#/components/parameters/XAppVersion"
- $ref: "#/components/parameters/XAppLanguage"
- $ref: "#/components/parameters/XAppPlatform"
post:
tags: ["Session management"]
operationId: login
summary: Log-in into system
description: |-
Perform a log-in action using username and password credentials.
Returns a token which can be used in authenticated requests.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
userid:
type: string
pattern: '^[a-zA-Z0-9]+$'
minLength: 3
maxLength: 255
password:
type: string
pattern: '^.*?$'
minLength: 8
maxLength: 255
responses:
"200":
description: Login successful
headers:
X-Access-Token:
description: Access token for authenticated requests
schema: { type: string }
"400": { $ref: "#/components/responses/BadRequest" }
"403":
description: Login failed
headers:
X-Message:
description: Error message
schema: { type: string }
"500": { $ref: "#/components/responses/InternalServerError" }
components:
schemas:
StatusInfo:
title: Status Info
type: object
properties:
status:
type: string
enum:
- info
- warning
- critical
- ""
title: { type: string }
message: { type: string }
url: { type: string }
responses:
Unauthorized:
description: The access token is missing or it's expired
BadRequest:
description: The request was not compliant with the documentation (eg. missing fields, etc)
InternalServerError:
description: The server encountered an internal error. Further info in server logs
securitySchemes:
LegacyAuth:
type: apiKey
in: header
name: X-App-Token
description: |-
App session token value. This value is sent by the server in the login
and session refresh APIs.
parameters:
XAppVersion:
schema:
type: string
pattern: '^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$'
minLength: 1
maxLength: 10
name: X-App-Version
in: header
required: true
description: App human readable version ("semantic version" format)
allowEmptyValue: false
XAppBuild:
schema: { type: integer }
name: X-App-Build
in: header
required: true
description: App build number
allowEmptyValue: false
XAppLanguage:
schema:
type: string
pattern: '^[a-z]{2}([-_][A-Z]{2})?$'
minLength: 2
maxLength: 5
name: X-App-Language
in: header
required: true
description: App language in ISO 639-1 format
allowEmptyValue: false
XAppPlatform:
schema:
type: string
enum: [ios, android]
name: X-App-Platform
in: header
required: true
description: App operating system / platform
allowEmptyValue: false
cat:
schema:
type: string
pattern: '^[a-zA-Z]+$'
minLength: 3
maxLength: 10
name: cat
in: path
required: true
description: Cat
allowEmptyValue: false