feat(12.2-02): add file removal, caption, reorder and protected downloads
- DELETE, PUT and POST reorder under .../{id}/files/{field}, each scoped by one parent query (404 for a foreign file)
- protected download and thumb routes: is_public=false only, nosniff, private no-store, sandbox CSP, inline only for jpeg/png/gif/webp
- the save applies deferred removals, replaces attachOne files and rechecks maxFiles and required
- blobs of deleted files are removed after commit
- swagger2openapi emits binary content for file responses
- admin OpenAPI, TS types, conformance, README and attachments docs
This commit is contained in:
Jakub Zych
@@ -662,3 +662,118 @@ func AdminFileList() {}
|
||||
// @Failure 422 {object} ErrorEnvelope
|
||||
// @Router /{vendor}/{plugin}/{controller}/{id}/files/{field} [post]
|
||||
func AdminFileUpload() {}
|
||||
|
||||
// AdminFileUpdate documents the caption route of a fileupload field.
|
||||
//
|
||||
// @Summary Save a file's title and description
|
||||
// @Description Saves at once (not deferred). The field must declare useCaption, otherwise 403. Omitted keys are left unchanged; unknown keys are refused.
|
||||
// @Tags admin
|
||||
// @Accept json
|
||||
// @Produce json
|
||||
// @Security BackendBearer
|
||||
// @Param vendor path string true "Vendor"
|
||||
// @Param plugin path string true "Plugin"
|
||||
// @Param controller path string true "Controller"
|
||||
// @Param id path integer true "Owner id (0 for the record being created)"
|
||||
// @Param field path string true "fileupload field name"
|
||||
// @Param file path integer true "File id"
|
||||
// @Param X-Session-Key header string false "Form session key; needed for a pending upload"
|
||||
// @Param body body AdminFileCaptionRequest true "Title and description"
|
||||
// @Success 200 {object} Envelope[FileItem]
|
||||
// @Failure 401 {object} ErrorEnvelope
|
||||
// @Failure 403 {object} ErrorEnvelope
|
||||
// @Failure 404 {object} ErrorEnvelope
|
||||
// @Failure 413 {object} ErrorEnvelope
|
||||
// @Failure 422 {object} ErrorEnvelope
|
||||
// @Router /{vendor}/{plugin}/{controller}/{id}/files/{field}/{file} [put]
|
||||
func AdminFileUpdate() {}
|
||||
|
||||
// AdminFileRemove documents the removal of a file from a fileupload field.
|
||||
//
|
||||
// @Summary Remove a file
|
||||
// @Description Removing an attached file is deferred to the record's next save with the same X-Session-Key; removing a pending upload deletes it at once.
|
||||
// @Tags admin
|
||||
// @Produce json
|
||||
// @Security BackendBearer
|
||||
// @Param vendor path string true "Vendor"
|
||||
// @Param plugin path string true "Plugin"
|
||||
// @Param controller path string true "Controller"
|
||||
// @Param id path integer true "Owner id (0 for the record being created)"
|
||||
// @Param field path string true "fileupload field name"
|
||||
// @Param file path integer true "File id"
|
||||
// @Param X-Session-Key header string true "Form session key"
|
||||
// @Success 200 {object} Envelope[FileMutationResult]
|
||||
// @Failure 401 {object} ErrorEnvelope
|
||||
// @Failure 403 {object} ErrorEnvelope
|
||||
// @Failure 404 {object} ErrorEnvelope
|
||||
// @Failure 422 {object} ErrorEnvelope
|
||||
// @Router /{vendor}/{plugin}/{controller}/{id}/files/{field}/{file} [delete]
|
||||
func AdminFileRemove() {}
|
||||
|
||||
// AdminFileReorder documents the reorder route of an attachMany field.
|
||||
//
|
||||
// @Summary Reorder the files of a field
|
||||
// @Description ids must be exactly the field's visible files (attached minus pending removals plus pending uploads); they receive the existing sort_order values in the submitted order, at once. attachMany only, otherwise 403.
|
||||
// @Tags admin
|
||||
// @Accept json
|
||||
// @Produce json
|
||||
// @Security BackendBearer
|
||||
// @Param vendor path string true "Vendor"
|
||||
// @Param plugin path string true "Plugin"
|
||||
// @Param controller path string true "Controller"
|
||||
// @Param id path integer true "Owner id (0 for the record being created)"
|
||||
// @Param field path string true "fileupload field name"
|
||||
// @Param X-Session-Key header string false "Form session key; needed for pending uploads"
|
||||
// @Param body body AdminIDsRequest true "File ids in the new order"
|
||||
// @Success 200 {object} Envelope[[]FileItem]
|
||||
// @Failure 401 {object} ErrorEnvelope
|
||||
// @Failure 403 {object} ErrorEnvelope
|
||||
// @Failure 404 {object} ErrorEnvelope
|
||||
// @Failure 413 {object} ErrorEnvelope
|
||||
// @Failure 422 {object} ErrorEnvelope
|
||||
// @Router /{vendor}/{plugin}/{controller}/{id}/files/{field}/reorder [post]
|
||||
func AdminFileReorder() {}
|
||||
|
||||
// AdminFileDownload documents the download of a protected file.
|
||||
//
|
||||
// @Summary Download a protected file
|
||||
// @Description Streams a file of a protected (Public false) relation that belongs to a record the admin may load, or is pending in the admin's own session. Public files are 404. JPEG, PNG, GIF and WebP are served inline with their type; everything else as an application/octet-stream attachment. Responses carry X-Content-Type-Options nosniff, Cache-Control private, no-store and a sandboxing Content-Security-Policy.
|
||||
// @Tags admin
|
||||
// @Produce octet-stream
|
||||
// @Security BackendBearer
|
||||
// @Param vendor path string true "Vendor"
|
||||
// @Param plugin path string true "Plugin"
|
||||
// @Param controller path string true "Controller"
|
||||
// @Param id path integer true "Owner id (0 for the record being created)"
|
||||
// @Param field path string true "fileupload field name"
|
||||
// @Param file path integer true "File id"
|
||||
// @Param X-Session-Key header string false "Form session key; needed for a pending upload"
|
||||
// @Success 200 {file} file
|
||||
// @Failure 401 {object} ErrorEnvelope
|
||||
// @Failure 403 {object} ErrorEnvelope
|
||||
// @Failure 404 {object} ErrorEnvelope
|
||||
// @Failure 422 {object} ErrorEnvelope
|
||||
// @Router /{vendor}/{plugin}/{controller}/{id}/files/{field}/{file}/download [get]
|
||||
func AdminFileDownload() {}
|
||||
|
||||
// AdminFileThumb documents the thumbnail of a protected image.
|
||||
//
|
||||
// @Summary Thumbnail of a protected image
|
||||
// @Description The preview thumbnail (imageWidth by imageHeight, 240 by 240 by default, in thumbOptions.mode) of a protected image file, scoped like the download route. A file that is not a JPEG, PNG, GIF or WebP image is 404.
|
||||
// @Tags admin
|
||||
// @Produce octet-stream
|
||||
// @Security BackendBearer
|
||||
// @Param vendor path string true "Vendor"
|
||||
// @Param plugin path string true "Plugin"
|
||||
// @Param controller path string true "Controller"
|
||||
// @Param id path integer true "Owner id (0 for the record being created)"
|
||||
// @Param field path string true "fileupload field name"
|
||||
// @Param file path integer true "File id"
|
||||
// @Param X-Session-Key header string false "Form session key; needed for a pending upload"
|
||||
// @Success 200 {file} file
|
||||
// @Failure 401 {object} ErrorEnvelope
|
||||
// @Failure 403 {object} ErrorEnvelope
|
||||
// @Failure 404 {object} ErrorEnvelope
|
||||
// @Failure 422 {object} ErrorEnvelope
|
||||
// @Router /{vendor}/{plugin}/{controller}/{id}/files/{field}/{file}/thumb [get]
|
||||
func AdminFileThumb() {}
|
||||
|
||||
Reference in New Issue
Block a user