source: TFP-WebServer/WebServer/src/WebAPI/APIs/Command.openapi.yaml@ 461

Last change on this file since 461 was 460, checked in by alloc, 2 years ago

More OpenAPI specs added
OpenAPI specs cleanup to have everything validate fine
Added CORS support to API endpoints
File size: 5.8 KB
Line 
1openapi: 3.1.0
2info:
3 title: Command
4 version: '1'
5
6components:
7 schemas:
8 CommandElement:
9 type: object
10 properties:
11 overloads:
12 type: array
13 items:
14 type: string
15 examples:
16 - [listplayers, lp]
17 description: Overload names for the command, including the main command name
18 command:
19 type: string
20 examples:
21 - listplayers
22 description: Main command name
23 description:
24 type: string
25 examples:
26 - lists all players
27 description: Short description text for the command
28 help:
29 type:
30 - string
31 - 'null'
32 description: Help text for the command if defined, null otherwise
33 allowed:
34 type: boolean
35 description: Can the command be executed with the permission level active for this request?
36 required:
37 - overloads
38 - command
39 - description
40
41 CommandsList:
42 type: array
43 items:
44 $ref: '#/components/schemas/CommandElement'
45
46 CommandsResult:
47 type: object
48 properties:
49 commands:
50 $ref: '#/components/schemas/CommandsList'
51 required:
52 - commands
53
54 CommandExecutedResultFull:
55 type: object
56 properties:
57 command:
58 type: string
59 examples:
60 - 'settime'
61 description: The command executed without arguments
62 parameters:
63 type: string
64 examples:
65 - '1 13 37'
66 description: The arguments of the executed command
67 result:
68 type: string
69 examples:
70 - 'Set time to 13616'
71 description: The output of the executed command
72 required:
73 - command
74 - parameters
75 - result
76 description: Full style command result
77
78 CommandExecutedResultSimple:
79 type: object
80 properties:
81 resultRaw:
82 type: string
83 examples:
84 - 'Set time to 13616'
85 description: The output of the executed command
86 required:
87 - resultRaw
88 description: Simple style command result
89
90
91 requestBodies:
92 CommandBodyIn:
93 content:
94 application/json:
95 schema:
96 type: object
97 properties:
98 command:
99 type: string
100 examples:
101 - 'settime 1 13 37'
102 description: Command to be executed, including any arguments
103 format:
104 type: string
105 enum:
106 - Full
107 - Simple
108 - Raw
109 description: Expected format of the returned execution result. Full being a full JSON object with info on the executed command and result, simple only returning a JSON object with the execution result and raw returning the execution result as plain text.
110 required:
111 - command
112 required: true
113
114
115 responses:
116 CommandsBodyOut:
117 description: Found commands
118 content:
119 application/json:
120 schema:
121 type: object
122 properties:
123 data:
124 $ref: '#/components/schemas/CommandsResult'
125 meta:
126 $ref: './openapi.yaml#/components/schemas/ResultEnvelopeMeta'
127 required:
128 - data
129 - meta
130
131
132 parameters:
133 CommandNameParameter:
134 name: name
135 in: path
136 required: true
137 schema:
138 type: string
139 description: Name of command to fetch
140
141
142paths:
143 /api/command:
144 get:
145 tags:
146 - Commands
147 summary: Commands list
148 description: Fetch a list of all commands
149 operationId: command.get
150 responses:
151 200:
152 description: List of commands
153 $ref: '#/components/responses/CommandsBodyOut'
154
155 post:
156 tags:
157 - Commands
158 summary: Command execute
159 description: Execute a command
160 operationId: command.post
161 requestBody:
162 $ref: '#/components/requestBodies/CommandBodyIn'
163 responses:
164 200:
165 description: Command executed successfully
166 content:
167 application/json:
168 schema:
169 oneOf:
170 - $ref: '#/components/schemas/CommandExecutedResultFull'
171 - $ref: '#/components/schemas/CommandExecutedResultSimple'
172 text/plain:
173 schema:
174 type: string
175 examples:
176 - 'Set time to 13616'
177 400:
178 description: Invalid request body, errorCode will be 'NO_COMMAND'
179 $ref: './openapi.yaml#/components/responses/HttpEmptyEnvelopedResponse'
180 404:
181 description: Command to be executed not found
182 $ref: './openapi.yaml#/components/responses/HttpEmptyEnvelopedResponse'
183 403:
184 description: Not allowed to execute the given command
185 $ref: './openapi.yaml#/components/responses/Unauthorized'
186 security:
187 - apiTokenName: []
188 apiTokenSecret: []
189 - sessionCookie: []
190
191 /api/command/{name}:
192 get:
193 tags:
194 - Commands
195 summary: Command show
196 description: Get info on a specific command
197 operationId: command.get.id
198 parameters:
199 - $ref: '#/components/parameters/CommandNameParameter'
200 responses:
201 200:
202 description: Single command
203 $ref: '#/components/responses/CommandsBodyOut'
204 404:
205 description: Command not found
206 $ref: './openapi.yaml#/components/responses/HttpEmptyEnvelopedResponse'
Note: See TracBrowser for help on using the repository browser.