From 5f63c5f7383dd7fde59a858fac0187fd5962a2ab Mon Sep 17 00:00:00 2001 From: Mike Kusold Date: Sun, 8 Dec 2024 16:11:21 -0700 Subject: [PATCH] Improve swagger generation (#370) * Improve swagger generation These issues are causing ogen-api to fail after I used the swagger converter. * Specify multipart/form-data routes Operations with parameters of "type: file" must include "multipart/form-data" in their "consumes" property * Fix example usage * fixup! Specify multipart/form-data routes * Fix final validation errors --- .github/workflows/partial-backend.yaml | 5 +++++ Taskfile.yml | 1 - backend/app/api/handlers/v1/v1_ctrl_auth.go | 6 ++---- backend/app/api/handlers/v1/v1_ctrl_items.go | 5 +++-- backend/app/api/handlers/v1/v1_ctrl_items_attachments.go | 1 + backend/app/api/handlers/v1/v1_ctrl_maint_entry.go | 2 ++ backend/app/api/handlers/v1/v1_ctrl_maintenance.go | 2 ++ backend/app/api/handlers/v1/v1_ctrl_notifiers.go | 1 - 8 files changed, 15 insertions(+), 8 deletions(-) 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:"admin@admin.com"` + 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(admin@admin.com) -// @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]