Skip to content

Commit 8ecde5a

Browse files
wl-estensdwl-estensd
authored
Merge pull request #73 from waterlinked/sonar-document-http-api
sonar: document HTTP API (swagger.json) and move API section
2 parents e4dcc82 + c5f0046 commit 8ecde5a

3 files changed

Lines changed: 410 additions & 11 deletions

File tree

‎docs/sonar-3d/sonar-3d-15-api-swagger/swagger.json‎

Lines changed: 390 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,390 @@
1+
{
2+
"swagger": "2.0",
3+
"info": {
4+
"contact": {}
5+
},
6+
"paths": {
7+
"/api/v1/integration/about": {
8+
"get": {
9+
"description": "Get system version",
10+
"tags": [
11+
"about",
12+
"integrationAPI"
13+
],
14+
"responses": {
15+
"200": {
16+
"description": "OK",
17+
"schema": {
18+
"$ref": "#/definitions/integrationapi.GinSystemVersion"
19+
}
20+
}
21+
}
22+
}
23+
},
24+
"/api/v1/integration/acoustics/enabled": {
25+
"get": {
26+
"description": "Get whether acoustics is enabled or disabled",
27+
"tags": [
28+
"acoustics",
29+
"integrationAPI"
30+
],
31+
"responses": {
32+
"200": {
33+
"description": "OK",
34+
"schema": {
35+
"type": "boolean"
36+
}
37+
},
38+
"204": {
39+
"description": "No Content"
40+
}
41+
}
42+
},
43+
"post": {
44+
"description": "Enable/disable acoustic imaging",
45+
"tags": [
46+
"acoustics",
47+
"integrationAPI"
48+
],
49+
"parameters": [
50+
{
51+
"description": " ",
52+
"name": "request",
53+
"in": "body",
54+
"required": true,
55+
"schema": {
56+
"type": "boolean"
57+
}
58+
}
59+
],
60+
"responses": {
61+
"204": {
62+
"description": "No Content"
63+
},
64+
"400": {
65+
"description": "Bad Request"
66+
},
67+
"408": {
68+
"description": "Request Timeout"
69+
},
70+
"409": {
71+
"description": "Conflict"
72+
}
73+
}
74+
}
75+
},
76+
"/api/v1/integration/acoustics/range": {
77+
"get": {
78+
"description": "Get range",
79+
"tags": [
80+
"acoustics",
81+
"integrationAPI"
82+
],
83+
"responses": {
84+
"200": {
85+
"description": "OK",
86+
"schema": {
87+
"$ref": "#/definitions/integrationapi.RangeResponse"
88+
}
89+
}
90+
}
91+
},
92+
"post": {
93+
"description": "Set range",
94+
"tags": [
95+
"acoustics",
96+
"integrationAPI"
97+
],
98+
"parameters": [
99+
{
100+
"description": " ",
101+
"name": "payload",
102+
"in": "body",
103+
"required": true,
104+
"schema": {
105+
"$ref": "#/definitions/integrationapi.RangeResponse"
106+
}
107+
}
108+
],
109+
"responses": {
110+
"204": {
111+
"description": "No Content"
112+
},
113+
"400": {
114+
"description": "Bad Request"
115+
},
116+
"409": {
117+
"description": "Conflict"
118+
},
119+
"500": {
120+
"description": "Internal Server Error"
121+
}
122+
}
123+
}
124+
},
125+
"/api/v1/integration/acoustics/speed_of_sound": {
126+
"get": {
127+
"description": "Get speed of sound",
128+
"tags": [
129+
"acoustics",
130+
"integrationAPI"
131+
],
132+
"responses": {
133+
"200": {
134+
"description": "OK",
135+
"schema": {
136+
"type": "number"
137+
}
138+
},
139+
"204": {
140+
"description": "No Content"
141+
}
142+
}
143+
},
144+
"post": {
145+
"description": "Set speed of sound",
146+
"tags": [
147+
"acoustics",
148+
"integrationAPI"
149+
],
150+
"parameters": [
151+
{
152+
"description": " ",
153+
"name": "request",
154+
"in": "body",
155+
"required": true,
156+
"schema": {
157+
"type": "number",
158+
"example": 1500
159+
}
160+
}
161+
],
162+
"responses": {
163+
"204": {
164+
"description": "No Content"
165+
},
166+
"400": {
167+
"description": "Bad Request"
168+
},
169+
"408": {
170+
"description": "Request Timeout"
171+
},
172+
"409": {
173+
"description": "Conflict"
174+
}
175+
}
176+
}
177+
},
178+
"/api/v1/integration/status": {
179+
"get": {
180+
"description": "Get the status of the system",
181+
"tags": [
182+
"status",
183+
"integrationAPI"
184+
],
185+
"responses": {
186+
"200": {
187+
"description": "OK",
188+
"schema": {
189+
"$ref": "#/definitions/integrationapi.GinStatusResponse"
190+
}
191+
}
192+
}
193+
}
194+
},
195+
"/api/v1/integration/temperature": {
196+
"get": {
197+
"description": "Get the internal temperature of the Sonar in degrees Celsius",
198+
"tags": [
199+
"status",
200+
"integrationAPI"
201+
],
202+
"responses": {
203+
"200": {
204+
"description": "OK",
205+
"schema": {
206+
"type": "number"
207+
}
208+
}
209+
}
210+
}
211+
},
212+
"/api/v1/integration/udp": {
213+
"get": {
214+
"description": "Get the current UDP configuration for how the Sonar outputs data.",
215+
"tags": [
216+
"integrationAPI"
217+
],
218+
"responses": {
219+
"200": {
220+
"description": "OK",
221+
"schema": {
222+
"$ref": "#/definitions/integrationapi.GinHandleUdpConfigPayload"
223+
}
224+
},
225+
"500": {
226+
"description": "Internal Server Error"
227+
}
228+
}
229+
},
230+
"post": {
231+
"description": "Set UDP configuration for how the Sonar should output data.",
232+
"tags": [
233+
"integrationAPI"
234+
],
235+
"parameters": [
236+
{
237+
"description": " ",
238+
"name": "payload",
239+
"in": "body",
240+
"required": true,
241+
"schema": {
242+
"$ref": "#/definitions/integrationapi.GinHandleUdpConfigPayload"
243+
}
244+
}
245+
],
246+
"responses": {
247+
"204": {
248+
"description": "No Content"
249+
},
250+
"400": {
251+
"description": "Bad Request"
252+
},
253+
"500": {
254+
"description": "Internal Server Error"
255+
}
256+
}
257+
}
258+
}
259+
},
260+
"definitions": {
261+
"integrationapi.GinHandleUdpConfigPayload": {
262+
"type": "object",
263+
"properties": {
264+
"mode": {
265+
"description": "Must be \"multicast\", \"unicast\" or \"disabled\"\n\nIf mode is \"disabled\", no UDP packets will be sent\n\nIf mode is \"multicast\", UDP packets will be sent on multicast\n\nIf mode is \"unicast\", UDP packets will be sent to the destination\nIP and port",
266+
"type": "string",
267+
"enum": [
268+
"multicast",
269+
"unicast",
270+
"disabled"
271+
],
272+
"example": "multicast"
273+
},
274+
"unicast_destination_ip": {
275+
"description": "The destination IP address if mode is \"unicast\".\nIf mode is \"unicast\", this must be a valid IP address.\nOtherwise, this must be a valid IP adddress or empty string.",
276+
"type": "string",
277+
"example": "192.168.1.100"
278+
},
279+
"unicast_destination_port": {
280+
"description": "The destination port if mode is \"unicast\".\nIf mode is \"unicast\", this must be a valid port.\nOtherwise, this must be a valid port or 0.",
281+
"type": "integer",
282+
"example": 12345
283+
}
284+
}
285+
},
286+
"integrationapi.GinStatusResponse": {
287+
"type": "object",
288+
"properties": {
289+
"api": {
290+
"description": "IntegrationAPI is the status of the UDP IntegrationAPI for external communication",
291+
"allOf": [
292+
{
293+
"$ref": "#/definitions/integrationapi.GinSystemStatusEntryResponse"
294+
}
295+
]
296+
},
297+
"calibration": {
298+
"description": "Calibration is the status of the Sonar calibration",
299+
"allOf": [
300+
{
301+
"$ref": "#/definitions/integrationapi.GinSystemStatusEntryResponse"
302+
}
303+
]
304+
},
305+
"temperature": {
306+
"description": "Temperature is the status of the Sonar temperature",
307+
"allOf": [
308+
{
309+
"$ref": "#/definitions/integrationapi.GinSystemStatusEntryResponse"
310+
}
311+
]
312+
}
313+
}
314+
},
315+
"integrationapi.GinSystemStatusEntryResponse": {
316+
"type": "object",
317+
"properties": {
318+
"id": {
319+
"description": "Unique ID for the status message",
320+
"type": "string",
321+
"example": "api-normal"
322+
},
323+
"message": {
324+
"description": "Message is a human readable message describing the status",
325+
"type": "string",
326+
"example": "Integration API is operational"
327+
},
328+
"operational": {
329+
"description": "Operational is true if the system is functional, false if it is not",
330+
"type": "boolean",
331+
"example": true
332+
},
333+
"severity": {
334+
"description": "Severity is the severity of the status message: info, warning, error",
335+
"type": "string",
336+
"example": "info"
337+
}
338+
}
339+
},
340+
"integrationapi.GinSystemVersion": {
341+
"type": "object",
342+
"properties": {
343+
"chipid": {
344+
"type": "string",
345+
"example": "0x12345678"
346+
},
347+
"hardware_revision": {
348+
"type": "integer",
349+
"example": 6
350+
},
351+
"is_ready": {
352+
"type": "boolean",
353+
"example": true
354+
},
355+
"product_id": {
356+
"type": "integer",
357+
"example": 21045
358+
},
359+
"product_name": {
360+
"type": "string",
361+
"example": "Sonar 3D-15"
362+
},
363+
"variant": {
364+
"type": "string"
365+
},
366+
"version": {
367+
"type": "string",
368+
"example": "1.5.1 (v1.3.0-26-gedccab6.2025-07-11T06:14:03.837365)"
369+
},
370+
"version_short": {
371+
"type": "string",
372+
"example": "1.5.1"
373+
}
374+
}
375+
},
376+
"integrationapi.RangeResponse": {
377+
"type": "object",
378+
"properties": {
379+
"max": {
380+
"type": "number",
381+
"example": 15
382+
},
383+
"min": {
384+
"type": "number",
385+
"example": 0
386+
}
387+
}
388+
}
389+
}
390+
}

0 commit comments

Comments
 (0)