Skip to content

Commit 38ec0c9

Browse files
dido18dido18
authored
docs: Add update endpoint to docs api
1 parent c2af470 commit 38ec0c9

File tree

3 files changed

+627
-1
lines changed

3 files changed

+627
-1
lines changed

‎cmd/gendoc/docs.go‎

Lines changed: 96 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,9 +24,10 @@ const (
2424
ApplicationTag Tag = "Application"
2525
BrickTag Tag = "Brick"
2626
AIModels Tag = "AIModels"
27+
SystemTag Tag = "System"
2728
)
2829

29-
var validTags = []Tag{ApplicationTag, BrickTag, AIModels}
30+
var validTags = []Tag{ApplicationTag, BrickTag, AIModels, SystemTag}
3031

3132
type Generator struct {
3233
reflector *openapi3.Reflector
@@ -115,6 +116,24 @@ func NewOpenApiGenerator(version string) *Generator {
115116
},
116117
},
117118
},
119+
"NoContent": {
120+
Response: &openapi3.Response{
121+
Description: "No Content",
122+
Content: map[string]openapi3.MediaType{
123+
"application/json": {
124+
Example: f.Ptr(interface{}(map[string]interface{}{
125+
"code": 204,
126+
"message": "No content to return.",
127+
})),
128+
Schema: &openapi3.SchemaOrRef{
129+
SchemaReference: &openapi3.SchemaReference{
130+
Ref: ErrorResponseSchema,
131+
},
132+
},
133+
},
134+
},
135+
},
136+
},
118137
"PreconditionFailed": {
119138
Response: &openapi3.Response{
120139
Description: "Precondition Failed",
@@ -573,6 +592,82 @@ Contains a JSON object with the details of an error.
573592
{StatusCode: http.StatusInternalServerError, Reference: "#/components/responses/InternalServerError"},
574593
},
575594
},
595+
{
596+
OperationId: "checkUpdate",
597+
Method: http.MethodGet,
598+
Path: "/v1/system/update/check",
599+
Parameters: (*struct {
600+
OnlyArduino bool `query:"only-arduino" description:"If true, check only for Arduino packages that require an upgrade. Default is false."`
601+
})(nil),
602+
CustomSuccessResponse: &CustomResponseDef{
603+
ContentType: "application/json",
604+
DataStructure: handlers.UpdateCheckResult{},
605+
Description: "Successful response",
606+
StatusCode: http.StatusOK,
607+
},
608+
Description: "Returns the details of packages to be upgraded.",
609+
Summary: "Get the packages that requires an upgrade",
610+
Tags: []Tag{SystemTag},
611+
PossibleErrors: []ErrorResponse{
612+
{StatusCode: http.StatusInternalServerError, Reference: "#/components/responses/InternalServerError"},
613+
{StatusCode: http.StatusBadRequest, Reference: "#/components/responses/BadRequest"},
614+
{StatusCode: http.StatusNoContent, Reference: "#/components/responses/NoContent"},
615+
},
616+
},
617+
{
618+
OperationId: "applyUpdate",
619+
Method: http.MethodPut,
620+
Path: "/v1/system/update/apply",
621+
Parameters: (*struct {
622+
OnlyArduino bool `query:"only-arduino" description:"If true, upgrade only the Arduino packages that require an upgrade. Default is false."`
623+
})(nil),
624+
CustomSuccessResponse: &CustomResponseDef{
625+
Description: "Successful response",
626+
StatusCode: http.StatusOK,
627+
},
628+
Description: "Start the upgrade process.",
629+
Summary: "Start the upgrade process in background",
630+
Tags: []Tag{SystemTag},
631+
PossibleErrors: []ErrorResponse{
632+
{StatusCode: http.StatusConflict, Reference: "#/components/responses/Conflict"},
633+
{StatusCode: http.StatusNoContent, Reference: "#/components/responses/NoContent"},
634+
{StatusCode: http.StatusInternalServerError, Reference: "#/components/responses/InternalServerError"},
635+
},
636+
},
637+
{
638+
OperationId: "eventsUpdate",
639+
Method: http.MethodGet,
640+
Path: "/v1/system/update/events",
641+
Request: nil,
642+
Description: "Returns the events of current update process.",
643+
Summary: "SSE stream of the update process",
644+
Tags: []Tag{SystemTag},
645+
CustomSuccessResponse: &CustomResponseDef{
646+
ContentType: "text/event-stream",
647+
DataStructure: "",
648+
Description: `A stream of Server-Sent Events (SSE) that notifies the progress of the update process.
649+
The client will receive events formatted as follows:
650+
651+
**Event 'log'**:
652+
Contains a log message of the apt upgrade command.
653+
'event: log'
654+
'data: "updating package: 0.25"'
655+
656+
**Event 'restarting'**:
657+
Contains a string with the message that the upgrade is completed and the system is restarting.
658+
'event: restarting'
659+
'data: Upgrade completed. Restarting'
660+
661+
**Event 'error'**:
662+
Contains a JSON object with the details of an error.
663+
'event: error'
664+
'data: {"code":"internal_service_err","message":"An error occurred during operation"}'
665+
`,
666+
},
667+
PossibleErrors: []ErrorResponse{
668+
{StatusCode: http.StatusInternalServerError, Reference: "#/components/responses/InternalServerError"},
669+
},
670+
},
576671
}
577672

578673
for _, op := range operations {

‎internal/api/docs/openapi.yaml‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ tags:
1010
- name: Application
1111
- name: Brick
1212
- name: AIModels
13+
- name: System
1314
paths:
1415
/v1/apps:
1516
get:
@@ -456,6 +457,93 @@ paths:
456457
summary: Get AI model details
457458
tags:
458459
- AIModels
460+
/v1/system/update/apply:
461+
put:
462+
description: Start the upgrade process.
463+
operationId: applyUpdate
464+
parameters:
465+
- description: If true, upgrade only the Arduino packages that require an upgrade.
466+
Default is false.
467+
in: query
468+
name: only-arduino
469+
schema:
470+
description: If true, upgrade only the Arduino packages that require an
471+
upgrade. Default is false.
472+
type: boolean
473+
responses:
474+
"200":
475+
description: Successful response
476+
"204":
477+
$ref: '#/components/responses/NoContent'
478+
"409":
479+
$ref: '#/components/responses/Conflict'
480+
"500":
481+
$ref: '#/components/responses/InternalServerError'
482+
summary: Start the upgrade process in background
483+
tags:
484+
- System
485+
/v1/system/update/check:
486+
get:
487+
description: Returns the details of packages to be upgraded.
488+
operationId: checkUpdate
489+
parameters:
490+
- description: If true, check only for Arduino packages that require an upgrade.
491+
Default is false.
492+
in: query
493+
name: only-arduino
494+
schema:
495+
description: If true, check only for Arduino packages that require an upgrade.
496+
Default is false.
497+
type: boolean
498+
responses:
499+
"200":
500+
content:
501+
application/json:
502+
schema:
503+
$ref: '#/components/schemas/UpdateCheckResult'
504+
description: Successful response
505+
"204":
506+
$ref: '#/components/responses/NoContent'
507+
"400":
508+
$ref: '#/components/responses/BadRequest'
509+
"500":
510+
$ref: '#/components/responses/InternalServerError'
511+
summary: Get the packages that requires an upgrade
512+
tags:
513+
- System
514+
/v1/system/update/events:
515+
get:
516+
description: Returns the events of current update process.
517+
operationId: eventsUpdate
518+
responses:
519+
"200":
520+
content:
521+
text/event-stream:
522+
schema:
523+
type: string
524+
description: |
525+
A stream of Server-Sent Events (SSE) that notifies the progress of the update process.
526+
The client will receive events formatted as follows:
527+
528+
**Event 'log'**:
529+
Contains a log message of the apt upgrade command.
530+
'event: log'
531+
'data: "updating package: 0.25"'
532+
533+
**Event 'restarting'**:
534+
Contains a string with the message that the upgrade is completed and the system is restarting.
535+
'event: restarting'
536+
'data: Upgrade completed. Restarting'
537+
538+
**Event 'error'**:
539+
Contains a JSON object with the details of an error.
540+
'event: error'
541+
'data: {"code":"internal_service_err","message":"An error occurred during operation"}'
542+
"500":
543+
$ref: '#/components/responses/InternalServerError'
544+
summary: SSE stream of the update process
545+
tags:
546+
- System
459547
/v1/version:
460548
get:
461549
description: returns the application current version
@@ -501,6 +589,15 @@ components:
501589
schema:
502590
$ref: '#/components/schemas/ErrorResponse'
503591
description: Internal Server Error
592+
NoContent:
593+
content:
594+
application/json:
595+
example:
596+
code: 204
597+
message: No content to return.
598+
schema:
599+
$ref: '#/components/schemas/ErrorResponse'
600+
description: No Content
504601
NotFound:
505602
content:
506603
application/json:
@@ -769,6 +866,23 @@ components:
769866
- failed
770867
type: string
771868
uniqueItems: true
869+
UpdateCheckResult:
870+
properties:
871+
packages:
872+
items:
873+
$ref: '#/components/schemas/UpgradablePackage'
874+
nullable: true
875+
type: array
876+
type: object
877+
UpgradablePackage:
878+
properties:
879+
from_version:
880+
type: string
881+
name:
882+
type: string
883+
to_version:
884+
type: string
885+
type: object
772886
VersionResponse:
773887
properties:
774888
version:

0 commit comments

Comments
 (0)