Skip to content

A continuation of HomeBox the inventory and organization system built for the Home User

Improve swagger generation (#370)

Mike Kusold5f63c5f7383d
diff --git a/.github/workflows/partial-backend.yaml b/.github/workflows/partial-backend.yaml
index fe4dac23..c534f902 100644
--- a/.github/workflows/partial-backend.yaml
+++ b/.github/workflows/partial-backend.yaml
@@ -34,3 +34,8 @@ jobs:
- name: Test
run: task go:coverage
+
+ - name: Validate OpenAPI definition
+ uses: swaggerexpert/swagger-editor-validate@v1
+ with:
+ definition-file: backend/app/api/static/docs/swagger.json
diff --git a/Taskfile.yml b/Taskfile.yml
index dc3f73c4..7f8abbe6 100644
--- a/Taskfile.yml
+++ b/Taskfile.yml
@@ -28,7 +28,6 @@ tasks:
- "./backend/internal/data/**"
- "./backend/internal/core/services/**/*"
- "./backend/app/tools/typegen/main.go"
-
typescript-types:
desc: Generates typescript types from swagger definition
cmds:
diff --git a/backend/app/api/handlers/v1/v1_ctrl_auth.go b/backend/app/api/handlers/v1/v1_ctrl_auth.go
index de5b6c2b..94dbda16 100644
--- a/backend/app/api/handlers/v1/v1_ctrl_auth.go
+++ b/backend/app/api/handlers/v1/v1_ctrl_auth.go
@@ -28,8 +28,8 @@ type (
}
LoginForm struct {
- Username string `json:"username"`
- Password string `json:"password"`
+ Username string `json:"username" example:"[email protected]"`
+ Password string `json:"password" example:"admin"`
StayLoggedIn bool `json:"stayLoggedIn"`
}
)
@@ -83,8 +83,6 @@ type AuthProvider interface {
// @Tags Authentication
// @Accept x-www-form-urlencoded
// @Accept application/json
-// @Param username formData string false "string" example([email protected])
-// @Param password formData string false "string" example(admin)
// @Param payload body LoginForm true "Login Data"
// @Param provider query string false "auth provider"
// @Produce json
diff --git a/backend/app/api/handlers/v1/v1_ctrl_items.go b/backend/app/api/handlers/v1/v1_ctrl_items.go
index b23534d6..ed6f1152 100644
--- a/backend/app/api/handlers/v1/v1_ctrl_items.go
+++ b/backend/app/api/handlers/v1/v1_ctrl_items.go
@@ -294,6 +294,7 @@ func (ctrl *V1Controller) HandleGetAllCustomFieldValues() errchain.HandlerFunc {
//
// @Summary Import Items
// @Tags Items
+// @Accept multipart/form-data
// @Produce json
// @Success 204
// @Param csv formData file true "Image to upload"
@@ -341,8 +342,8 @@ func (ctrl *V1Controller) HandleItemsExport() errchain.HandlerFunc {
log.Err(err).Msg("failed to export items")
return validate.NewRequestError(err, http.StatusInternalServerError)
}
-
- timestamp := time.Now().Format("2006-01-02_15-04-05") // YYYY-MM-DD_HH-MM-SS format
+
+ timestamp := time.Now().Format("2006-01-02_15-04-05") // YYYY-MM-DD_HH-MM-SS format
filename := fmt.Sprintf("homebox-items_%s.csv", timestamp) // add timestamp to filename
w.Header().Set("Content-Type", "text/csv")
diff --git a/backend/app/api/handlers/v1/v1_ctrl_items_attachments.go b/backend/app/api/handlers/v1/v1_ctrl_items_attachments.go
index 61b3b9a5..18babb5d 100644
--- a/backend/app/api/handlers/v1/v1_ctrl_items_attachments.go
+++ b/backend/app/api/handlers/v1/v1_ctrl_items_attachments.go
@@ -25,6 +25,7 @@ type (
//
// @Summary Create Item Attachment
// @Tags Items Attachments
+// @Accept multipart/form-data
// @Produce json
// @Param id path string true "Item ID"
// @Param file formData file true "File attachment"
diff --git a/backend/app/api/handlers/v1/v1_ctrl_maint_entry.go b/backend/app/api/handlers/v1/v1_ctrl_maint_entry.go
index e9f1f97c..b981405b 100644
--- a/backend/app/api/handlers/v1/v1_ctrl_maint_entry.go
+++ b/backend/app/api/handlers/v1/v1_ctrl_maint_entry.go
@@ -15,6 +15,7 @@ import (
// @Summary Get Maintenance Log
// @Tags Item Maintenance
// @Produce json
+// @Param id path string true "Item ID"
// @Param filters query repo.MaintenanceFilters false "which maintenance to retrieve"
// @Success 200 {array} repo.MaintenanceEntryWithDetails[]
// @Router /v1/items/{id}/maintenance [GET]
@@ -33,6 +34,7 @@ func (ctrl *V1Controller) HandleMaintenanceLogGet() errchain.HandlerFunc {
// @Summary Create Maintenance Entry
// @Tags Item Maintenance
// @Produce json
+// @Param id path string true "Item ID"
// @Param payload body repo.MaintenanceEntryCreate true "Entry Data"
// @Success 201 {object} repo.MaintenanceEntry
// @Router /v1/items/{id}/maintenance [POST]
diff --git a/backend/app/api/handlers/v1/v1_ctrl_maintenance.go b/backend/app/api/handlers/v1/v1_ctrl_maintenance.go
index 647bfa70..a774cc3e 100644
--- a/backend/app/api/handlers/v1/v1_ctrl_maintenance.go
+++ b/backend/app/api/handlers/v1/v1_ctrl_maintenance.go
@@ -33,6 +33,7 @@ func (ctrl *V1Controller) HandleMaintenanceGetAll() errchain.HandlerFunc {
// @Summary Update Maintenance Entry
// @Tags Maintenance
// @Produce json
+// @Param id path string true "Maintenance ID"
// @Param payload body repo.MaintenanceEntryUpdate true "Entry Data"
// @Success 200 {object} repo.MaintenanceEntry
// @Router /v1/maintenance/{id} [PUT]
@@ -51,6 +52,7 @@ func (ctrl *V1Controller) HandleMaintenanceEntryUpdate() errchain.HandlerFunc {
// @Summary Delete Maintenance Entry
// @Tags Maintenance
// @Produce json
+// @Param id path string true "Maintenance ID"
// @Success 204
// @Router /v1/maintenance/{id} [DELETE]
// @Security Bearer
diff --git a/backend/app/api/handlers/v1/v1_ctrl_notifiers.go b/backend/app/api/handlers/v1/v1_ctrl_notifiers.go
index f46b9102..697605c4 100644
--- a/backend/app/api/handlers/v1/v1_ctrl_notifiers.go
+++ b/backend/app/api/handlers/v1/v1_ctrl_notifiers.go
@@ -86,7 +86,6 @@ func (ctrl *V1Controller) HandleUpdateNotifier() errchain.HandlerFunc {
// @Summary Test Notifier
// @Tags Notifiers
// @Produce json
-// @Param id path string true "Notifier ID"
// @Param url query string true "URL"
// @Success 204
// @Router /v1/notifiers/test [POST]