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

Last change on this file since 460 was 460, checked in by alloc, 15 months ago

More OpenAPI specs added
OpenAPI specs cleanup to have everything validate fine
Added CORS support to API endpoints
File size: 5.8 KB
RevLine 
[460]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.