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

@@ -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

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:

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

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")

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"

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]

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

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]