homebox/backend/app/api/docs/swagger.yaml
Hayden 31b34241e0
feat: item-attachments CRUD (#22)
* change /content/ -> /homebox/

* add cache to code generators

* update env variables to set data storage

* update env variables

* set env variables in prod container

* implement attachment post route (WIP)

* get attachment endpoint

* attachment download

* implement string utilities lib

* implement generic drop zone

* use explicit truncate

* remove clean dir

* drop strings composable for lib

* update item types and add attachments

* add attachment API

* implement service context

* consolidate API code

* implement editing attachments

* implement upload limit configuration

* improve error handling

* add docs for max upload size

* fix test cases
2022-09-24 11:33:38 -08:00

1023 lines
21 KiB
YAML

basePath: /api
definitions:
server.Result:
properties:
details: {}
error:
type: boolean
item: {}
message:
type: string
type: object
server.Results:
properties:
items:
type: any
type: object
server.ValidationError:
properties:
field:
type: string
reason:
type: string
type: object
types.ApiSummary:
properties:
build:
$ref: '#/definitions/types.Build'
health:
type: boolean
message:
type: string
title:
type: string
versions:
items:
type: string
type: array
type: object
types.Build:
properties:
buildTime:
type: string
commit:
type: string
version:
type: string
type: object
types.DocumentOut:
properties:
id:
type: string
path:
type: string
title:
type: string
type: object
types.ItemAttachment:
properties:
createdAt:
type: string
document:
$ref: '#/definitions/types.DocumentOut'
id:
type: string
type:
type: string
updatedAt:
type: string
type: object
types.ItemAttachmentToken:
properties:
token:
type: string
type: object
types.ItemAttachmentUpdate:
properties:
title:
type: string
type:
type: string
type: object
types.ItemCreate:
properties:
description:
type: string
labelIds:
items:
type: string
type: array
locationId:
description: Edges
type: string
name:
type: string
type: object
types.ItemOut:
properties:
attachments:
items:
$ref: '#/definitions/types.ItemAttachment'
type: array
createdAt:
type: string
description:
type: string
id:
type: string
insured:
type: boolean
labels:
items:
$ref: '#/definitions/types.LabelSummary'
type: array
lifetimeWarranty:
description: Warranty
type: boolean
location:
$ref: '#/definitions/types.LocationSummary'
description: Edges
manufacturer:
type: string
modelNumber:
type: string
name:
type: string
notes:
description: Extras
type: string
purchaseFrom:
type: string
purchasePrice:
example: "0"
type: string
purchaseTime:
description: Purchase
type: string
quantity:
type: integer
serialNumber:
description: Identifications
type: string
soldNotes:
type: string
soldPrice:
example: "0"
type: string
soldTime:
description: Sold
type: string
soldTo:
type: string
updatedAt:
type: string
warrantyDetails:
type: string
warrantyExpires:
type: string
type: object
types.ItemSummary:
properties:
createdAt:
type: string
description:
type: string
id:
type: string
insured:
type: boolean
labels:
items:
$ref: '#/definitions/types.LabelSummary'
type: array
lifetimeWarranty:
description: Warranty
type: boolean
location:
$ref: '#/definitions/types.LocationSummary'
description: Edges
manufacturer:
type: string
modelNumber:
type: string
name:
type: string
notes:
description: Extras
type: string
purchaseFrom:
type: string
purchasePrice:
example: "0"
type: string
purchaseTime:
description: Purchase
type: string
quantity:
type: integer
serialNumber:
description: Identifications
type: string
soldNotes:
type: string
soldPrice:
example: "0"
type: string
soldTime:
description: Sold
type: string
soldTo:
type: string
updatedAt:
type: string
warrantyDetails:
type: string
warrantyExpires:
type: string
type: object
types.ItemUpdate:
properties:
description:
type: string
id:
type: string
insured:
type: boolean
labelIds:
items:
type: string
type: array
lifetimeWarranty:
description: Warranty
type: boolean
locationId:
description: Edges
type: string
manufacturer:
type: string
modelNumber:
type: string
name:
type: string
notes:
description: Extras
type: string
purchaseFrom:
type: string
purchasePrice:
example: "0"
type: string
purchaseTime:
description: Purchase
type: string
quantity:
type: integer
serialNumber:
description: Identifications
type: string
soldNotes:
type: string
soldPrice:
example: "0"
type: string
soldTime:
description: Sold
type: string
soldTo:
type: string
warrantyDetails:
type: string
warrantyExpires:
type: string
type: object
types.LabelCreate:
properties:
color:
type: string
description:
type: string
name:
type: string
type: object
types.LabelOut:
properties:
createdAt:
type: string
description:
type: string
id:
type: string
items:
items:
$ref: '#/definitions/types.ItemSummary'
type: array
name:
type: string
updatedAt:
type: string
type: object
types.LabelSummary:
properties:
createdAt:
type: string
description:
type: string
id:
type: string
name:
type: string
updatedAt:
type: string
type: object
types.LocationCount:
properties:
createdAt:
type: string
description:
type: string
id:
type: string
itemCount:
type: integer
name:
type: string
updatedAt:
type: string
type: object
types.LocationCreate:
properties:
description:
type: string
name:
type: string
type: object
types.LocationOut:
properties:
createdAt:
type: string
description:
type: string
id:
type: string
items:
items:
$ref: '#/definitions/types.ItemSummary'
type: array
name:
type: string
updatedAt:
type: string
type: object
types.LocationSummary:
properties:
createdAt:
type: string
description:
type: string
id:
type: string
name:
type: string
updatedAt:
type: string
type: object
types.TokenResponse:
properties:
expiresAt:
type: string
token:
type: string
type: object
types.UserIn:
properties:
email:
type: string
name:
type: string
password:
type: string
type: object
types.UserOut:
properties:
email:
type: string
groupId:
type: string
groupName:
type: string
id:
type: string
isSuperuser:
type: boolean
name:
type: string
type: object
types.UserRegistration:
properties:
groupName:
type: string
user:
$ref: '#/definitions/types.UserIn'
type: object
types.UserUpdate:
properties:
email:
type: string
name:
type: string
type: object
info:
contact:
name: Don't
description: This is a simple Rest API Server Template that implements some basic
User and Authentication patterns to help you get started and bootstrap your next
project!.
license:
name: MIT
title: Go API Templates
version: "1.0"
paths:
/v1/items:
get:
produces:
- application/json
responses:
"200":
description: OK
schema:
allOf:
- $ref: '#/definitions/server.Results'
- properties:
items:
items:
$ref: '#/definitions/types.ItemSummary'
type: array
type: object
security:
- Bearer: []
summary: Get All Items
tags:
- Items
post:
parameters:
- description: Item Data
in: body
name: payload
required: true
schema:
$ref: '#/definitions/types.ItemCreate'
produces:
- application/json
responses:
"200":
description: OK
schema:
$ref: '#/definitions/types.ItemSummary'
security:
- Bearer: []
summary: Create a new item
tags:
- Items
/v1/items/{id}:
delete:
parameters:
- description: Item ID
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"204":
description: ""
security:
- Bearer: []
summary: deletes a item
tags:
- Items
get:
parameters:
- description: Item ID
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"200":
description: OK
schema:
$ref: '#/definitions/types.ItemOut'
security:
- Bearer: []
summary: Gets a item and fields
tags:
- Items
put:
parameters:
- description: Item ID
in: path
name: id
required: true
type: string
- description: Item Data
in: body
name: payload
required: true
schema:
$ref: '#/definitions/types.ItemUpdate'
produces:
- application/json
responses:
"200":
description: OK
schema:
$ref: '#/definitions/types.ItemOut'
security:
- Bearer: []
summary: updates a item
tags:
- Items
/v1/items/{id}/attachments:
post:
parameters:
- description: Item ID
in: path
name: id
required: true
type: string
- description: File attachment
in: formData
name: file
required: true
type: file
- description: Type of file
in: formData
name: type
required: true
type: string
- description: name of the file including extension
in: formData
name: name
required: true
type: string
produces:
- application/json
responses:
"200":
description: OK
schema:
$ref: '#/definitions/types.ItemOut'
"422":
description: Unprocessable Entity
schema:
items:
$ref: '#/definitions/server.ValidationError'
type: array
security:
- Bearer: []
summary: imports items into the database
tags:
- Items
/v1/items/{id}/attachments/{attachment_id}:
delete:
parameters:
- description: Item ID
in: path
name: id
required: true
type: string
- description: Attachment ID
in: path
name: attachment_id
required: true
type: string
responses:
"204":
description: ""
security:
- Bearer: []
summary: retrieves an attachment for an item
tags:
- Items
get:
parameters:
- description: Item ID
in: path
name: id
required: true
type: string
- description: Attachment ID
in: path
name: attachment_id
required: true
type: string
produces:
- application/octet-stream
responses:
"200":
description: OK
schema:
$ref: '#/definitions/types.ItemAttachmentToken'
security:
- Bearer: []
summary: retrieves an attachment for an item
tags:
- Items
put:
parameters:
- description: Item ID
in: path
name: id
required: true
type: string
- description: Attachment ID
in: path
name: attachment_id
required: true
type: string
- description: Attachment Update
in: body
name: payload
required: true
schema:
$ref: '#/definitions/types.ItemAttachmentUpdate'
responses:
"200":
description: OK
schema:
$ref: '#/definitions/types.ItemOut'
security:
- Bearer: []
summary: retrieves an attachment for an item
tags:
- Items
/v1/items/{id}/attachments/download:
get:
parameters:
- description: Item ID
in: path
name: id
required: true
type: string
- description: Attachment token
in: query
name: token
required: true
type: string
produces:
- application/octet-stream
responses:
"200":
description: ""
security:
- Bearer: []
summary: retrieves an attachment for an item
tags:
- Items
/v1/items/import:
post:
parameters:
- description: Image to upload
in: formData
name: csv
required: true
type: file
produces:
- application/json
responses:
"204":
description: ""
security:
- Bearer: []
summary: imports items into the database
tags:
- Items
/v1/labels:
get:
produces:
- application/json
responses:
"200":
description: OK
schema:
allOf:
- $ref: '#/definitions/server.Results'
- properties:
items:
items:
$ref: '#/definitions/types.LabelOut'
type: array
type: object
security:
- Bearer: []
summary: Get All Labels
tags:
- Labels
post:
parameters:
- description: Label Data
in: body
name: payload
required: true
schema:
$ref: '#/definitions/types.LabelCreate'
produces:
- application/json
responses:
"200":
description: OK
schema:
$ref: '#/definitions/types.LabelSummary'
security:
- Bearer: []
summary: Create a new label
tags:
- Labels
/v1/labels/{id}:
delete:
parameters:
- description: Label ID
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"204":
description: ""
security:
- Bearer: []
summary: deletes a label
tags:
- Labels
get:
parameters:
- description: Label ID
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"200":
description: OK
schema:
$ref: '#/definitions/types.LabelOut'
security:
- Bearer: []
summary: Gets a label and fields
tags:
- Labels
put:
parameters:
- description: Label ID
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"200":
description: OK
schema:
$ref: '#/definitions/types.LabelOut'
security:
- Bearer: []
summary: updates a label
tags:
- Labels
/v1/locations:
get:
produces:
- application/json
responses:
"200":
description: OK
schema:
allOf:
- $ref: '#/definitions/server.Results'
- properties:
items:
items:
$ref: '#/definitions/types.LocationCount'
type: array
type: object
security:
- Bearer: []
summary: Get All Locations
tags:
- Locations
post:
parameters:
- description: Location Data
in: body
name: payload
required: true
schema:
$ref: '#/definitions/types.LocationCreate'
produces:
- application/json
responses:
"200":
description: OK
schema:
$ref: '#/definitions/types.LocationSummary'
security:
- Bearer: []
summary: Create a new location
tags:
- Locations
/v1/locations/{id}:
delete:
parameters:
- description: Location ID
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"204":
description: ""
security:
- Bearer: []
summary: deletes a location
tags:
- Locations
get:
parameters:
- description: Location ID
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"200":
description: OK
schema:
$ref: '#/definitions/types.LocationOut'
security:
- Bearer: []
summary: Gets a location and fields
tags:
- Locations
put:
parameters:
- description: Location ID
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"200":
description: OK
schema:
$ref: '#/definitions/types.LocationOut'
security:
- Bearer: []
summary: updates a location
tags:
- Locations
/v1/status:
get:
produces:
- application/json
responses:
"200":
description: OK
schema:
$ref: '#/definitions/types.ApiSummary'
summary: Retrieves the basic information about the API
tags:
- Base
/v1/users/login:
post:
consumes:
- application/x-www-form-urlencoded
- application/json
parameters:
- description: string
example: admin@admin.com
in: formData
name: username
type: string
- description: string
example: admin
in: formData
name: password
type: string
produces:
- application/json
responses:
"200":
description: OK
schema:
$ref: '#/definitions/types.TokenResponse'
summary: User Login
tags:
- Authentication
/v1/users/logout:
post:
responses:
"204":
description: ""
security:
- Bearer: []
summary: User Logout
tags:
- Authentication
/v1/users/refresh:
get:
description: |-
handleAuthRefresh returns a handler that will issue a new token from an existing token.
This does not validate that the user still exists within the database.
responses:
"200":
description: ""
security:
- Bearer: []
summary: User Token Refresh
tags:
- Authentication
/v1/users/register:
post:
parameters:
- description: User Data
in: body
name: payload
required: true
schema:
$ref: '#/definitions/types.UserRegistration'
produces:
- application/json
responses:
"204":
description: ""
summary: Get the current user
tags:
- User
/v1/users/self:
delete:
produces:
- application/json
responses:
"204":
description: ""
security:
- Bearer: []
summary: Deletes the user account
tags:
- User
get:
produces:
- application/json
responses:
"200":
description: OK
schema:
allOf:
- $ref: '#/definitions/server.Result'
- properties:
item:
$ref: '#/definitions/types.UserOut'
type: object
security:
- Bearer: []
summary: Get the current user
tags:
- User
put:
parameters:
- description: User Data
in: body
name: payload
required: true
schema:
$ref: '#/definitions/types.UserUpdate'
produces:
- application/json
responses:
"200":
description: OK
schema:
allOf:
- $ref: '#/definitions/server.Result'
- properties:
item:
$ref: '#/definitions/types.UserUpdate'
type: object
security:
- Bearer: []
summary: Update the current user
tags:
- User
/v1/users/self/password:
put:
produces:
- application/json
responses:
"204":
description: ""
security:
- Bearer: []
summary: 'Update the current user''s password // TODO:'
tags:
- User
securityDefinitions:
Bearer:
description: '"Type ''Bearer TOKEN'' to correctly set the API Key"'
in: header
name: Authorization
type: apiKey
swagger: "2.0"