mirror of
https://github.com/linux-odyssey/linux-odyssey.git
synced 2026-11-06 03:20:13 +08:00
Lin, Hung-Shin
49417c405a
* extract icon library from main.js * extract router from main.js * failure with error in passport * add example to swagger
544 lines
14 KiB
YAML
544 lines
14 KiB
YAML
openapi: 3.0.0
|
|
servers:
|
|
- url: /api/v1
|
|
- url: https://odyssey.wancat.cc/api/v1
|
|
- url: http://localhost:3000/api/v1
|
|
info:
|
|
description: Linux Odyssey API
|
|
version: '1.0.0'
|
|
title: Session API
|
|
contact:
|
|
email: wancat@wancat.cc
|
|
license:
|
|
name: Apache 2.0
|
|
url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
|
|
tags:
|
|
- name: admins
|
|
description: Secured Admin-only calls
|
|
- name: developers
|
|
description: Operations available to regular developers
|
|
paths:
|
|
/sessions:
|
|
get:
|
|
tags:
|
|
- signed-in
|
|
summary: list existing sessions of current user
|
|
security:
|
|
- BearerAuth: []
|
|
parameters:
|
|
- in: query
|
|
name: quest_id
|
|
description: find sessions by quest id
|
|
schema:
|
|
type: string
|
|
- in: query
|
|
name: status
|
|
description: find sessions by status
|
|
schema:
|
|
type: string
|
|
enum: [active, finished, inactive]
|
|
responses:
|
|
'200':
|
|
description: list of existing session
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/SessionSummary'
|
|
|
|
post:
|
|
summary: create a new session for current user
|
|
tags:
|
|
- signed-in
|
|
security:
|
|
- BearerAuth: []
|
|
requestBody:
|
|
description: session data
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
quest_id:
|
|
type: string
|
|
example: helloworld
|
|
responses:
|
|
'201':
|
|
description: session created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Session'
|
|
'400':
|
|
description: Invalid input
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
|
|
/sessions/{session_id}:
|
|
get:
|
|
tags:
|
|
- signed-in
|
|
summary: get a specific session of current user by ID
|
|
security:
|
|
- BearerAuth: []
|
|
parameters:
|
|
- in: path
|
|
name: session_id
|
|
description: ID of the session to retrieve
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: objectId
|
|
example: 64b7a3a3c182b4826dd1aaa1
|
|
responses:
|
|
'200':
|
|
description: the session
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Session'
|
|
'404':
|
|
description: cannot find specific session
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
delete:
|
|
tags:
|
|
- signed-in
|
|
summary: delete a specific session by ID
|
|
security:
|
|
- BearerAuth: []
|
|
parameters:
|
|
- in: path
|
|
name: session_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: objectId
|
|
example: 64b7a3a3c182b4826dd1aaa1
|
|
responses:
|
|
'204':
|
|
description: Session successfully deleted
|
|
|
|
'404':
|
|
description: Session not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
example: 'Session not found.'
|
|
'401':
|
|
description: Unauthorized
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
example: 'Unauthorized.'
|
|
|
|
/auth/register:
|
|
post:
|
|
summary: Register a new user
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
username:
|
|
type: string
|
|
format: username
|
|
example: alex
|
|
email:
|
|
type: string
|
|
format: email
|
|
example: alex@example.com
|
|
password:
|
|
type: string
|
|
format: password
|
|
example: 123456
|
|
responses:
|
|
'201':
|
|
description: User created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
token:
|
|
type: string
|
|
description: Access token
|
|
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
|
'400':
|
|
description: Bad Request
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
example: Missing username, email or password
|
|
'409':
|
|
description: Conflict
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
example: User already exists
|
|
|
|
/auth/login:
|
|
post:
|
|
summary: Log in a user
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
username:
|
|
type: string
|
|
format: username
|
|
example: alex
|
|
password:
|
|
type: string
|
|
format: password
|
|
example: 123456
|
|
responses:
|
|
'200':
|
|
description: User logged in
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
token:
|
|
type: string
|
|
description: Access token
|
|
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
|
'400':
|
|
description: Bad Request
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
example: Missing username or password
|
|
'401':
|
|
description: Unauthorized
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
example: Incorrect username or password
|
|
|
|
/auth/check:
|
|
get:
|
|
summary: Check if the username is already taken
|
|
parameters:
|
|
- in: query
|
|
name: username
|
|
description: username to check
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: username
|
|
example: alex
|
|
responses:
|
|
'200':
|
|
description: Username is available
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
example: Username is available
|
|
'409':
|
|
description: Username is already taken
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
example: Username is already taken
|
|
|
|
/profile:
|
|
get:
|
|
summary: Get the profile of current logged-in user
|
|
security:
|
|
- BearerAuth: []
|
|
responses:
|
|
'200':
|
|
description: Get user's profile
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/User'
|
|
|
|
/quests:
|
|
get:
|
|
summary: Get quests list
|
|
responses:
|
|
'200':
|
|
description: Quests summary list
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/QuestSummary'
|
|
|
|
/quests/{quest_id}:
|
|
get:
|
|
summary: get a quest's detail by name
|
|
parameters:
|
|
- in: path
|
|
name: quest_id
|
|
description: name of the quest to retrieve
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: the quest
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Quest'
|
|
'404':
|
|
description: cannot find specific quest
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
|
|
/commands:
|
|
post:
|
|
summary: Record a command that was executed in a session
|
|
tags:
|
|
- signed-in
|
|
security:
|
|
- BearerAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Command'
|
|
responses:
|
|
'201':
|
|
description: Command recorded successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CommandResponse'
|
|
'400':
|
|
description: Invalid request body
|
|
'401':
|
|
description: Unauthorized
|
|
|
|
components:
|
|
schemas:
|
|
User:
|
|
type: object
|
|
properties:
|
|
_id:
|
|
type: string
|
|
format: objectId
|
|
example: 64b7a3a3c182b4826dd1aaa1
|
|
username:
|
|
type: string
|
|
example: 'alex'
|
|
email:
|
|
type: string
|
|
format: email
|
|
Quest:
|
|
type: object
|
|
properties:
|
|
_id:
|
|
type: string
|
|
example: helloworld
|
|
title:
|
|
type: string
|
|
example: Hello World
|
|
instruction:
|
|
type: string
|
|
example: 'In this quest, you need to learn how to use `ls` to list the file.'
|
|
order:
|
|
type: number
|
|
|
|
QuestSummary:
|
|
type: object
|
|
properties:
|
|
_id:
|
|
type: string
|
|
example: helloworld
|
|
title:
|
|
type: string
|
|
example: Hello World
|
|
order:
|
|
type: number
|
|
|
|
Session:
|
|
type: object
|
|
properties:
|
|
_id:
|
|
type: string
|
|
format: objectId
|
|
example: 64b7a3a3c182b4826dd1aaa1
|
|
user:
|
|
$ref: '#/components/schemas/User'
|
|
quest:
|
|
$ref: '#/components/schemas/Quest'
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
updated_at:
|
|
type: string
|
|
format: date-time
|
|
finished_at:
|
|
type: string
|
|
format: date-time
|
|
hints:
|
|
type: array
|
|
items:
|
|
type: string
|
|
example: '`ls -al` to list detail information of all files.'
|
|
progress:
|
|
type: string
|
|
description: current stage id
|
|
example: helloworld
|
|
completed:
|
|
type: array
|
|
description: list of completed stage ids
|
|
items:
|
|
type: string
|
|
example: helloworld
|
|
|
|
SessionSummary:
|
|
type: object
|
|
properties:
|
|
_id:
|
|
type: string
|
|
format: objectId
|
|
example: 64b7a3a3c182b4826dd1aaa1
|
|
quest:
|
|
$ref: '#/components/schemas/Quest'
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
updated_at:
|
|
type: string
|
|
format: date-time
|
|
finished_at:
|
|
type: string
|
|
format: date-time
|
|
|
|
TreeNode:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
display:
|
|
type: boolean
|
|
children:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/TreeNode'
|
|
|
|
Command:
|
|
type: object
|
|
required:
|
|
- pwd
|
|
- command
|
|
properties:
|
|
pwd:
|
|
type: string
|
|
example: '/root'
|
|
description: The current working directory
|
|
command:
|
|
type: string
|
|
example: 'ls -al /'
|
|
description: The command that was executed
|
|
output:
|
|
type: string
|
|
description: The output of the command
|
|
error:
|
|
type: string
|
|
description: The error message of the command
|
|
|
|
CommandResponse:
|
|
type: object
|
|
properties:
|
|
responses:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/CommandResponseItem'
|
|
hints:
|
|
type: array
|
|
items:
|
|
type: string
|
|
example: '`ls -al` to list detail information of all files.'
|
|
end:
|
|
type: boolean
|
|
description: Whether the session has ended
|
|
|
|
CommandResponseItem:
|
|
type: object
|
|
required:
|
|
- type
|
|
- content
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum: [narrative, dialogue]
|
|
content:
|
|
type: array
|
|
items:
|
|
type: string
|
|
example: 'You have completed the quest!'
|
|
color:
|
|
type: string
|
|
enum: [red, green, blue, yellow, purple, cyan, white, gray, black]
|
|
speaker:
|
|
type: string
|
|
example: 'Unix Spirit'
|
|
|
|
securitySchemes:
|
|
BearerAuth:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|