docs: add missing swagger types and examples (#231)

Resolves #139.

Author: morremeyer

api/docs.go

@@ -31,7 +31,7 @@ type BudgetLinks struct {
 	Accounts     string `json:"accounts" example:"https://example.com/api/v1/accounts?budget=550dc009-cea6-4c12-b2a5-03446eb7b7cf"`
 	Categories   string `json:"categories" example:"https://example.com/api/v1/categories?budget=550dc009-cea6-4c12-b2a5-03446eb7b7cf"`
 	Transactions string `json:"transactions" example:"https://example.com/api/v1/transactions?budget=550dc009-cea6-4c12-b2a5-03446eb7b7cf"`
-	Month        string `json:"month" example:"https://example.com/api/v1/budgets/550dc009-cea6-4c12-b2a5-03446eb7b7cf/2022-03"`
+	Month        string `json:"month" example:"https://example.com/api/v1/budgets/550dc009-cea6-4c12-b2a5-03446eb7b7cf/YYYY-MM"` // This will always end in 'YYYY-MM' for clients to use replace with actual numbers.
 }
 
 type BudgetMonthResponse struct {

api/swagger.json

@@ -32,7 +32,7 @@ type EnvelopeMonthResponse struct {
 type EnvelopeLinks struct {
 	Self        string `json:"self" example:"https://example.com/api/v1/envelopes/45b6b5b9-f746-4ae9-b77b-7688b91f8166"`
 	Allocations string `json:"allocations" example:"https://example.com/api/v1/allocations?envelope=45b6b5b9-f746-4ae9-b77b-7688b91f8166"`
-	Month       string `json:"month" example:"https://example.com/api/v1/envelopes/45b6b5b9-f746-4ae9-b77b-7688b91f8166/2019-03"`
+	Month       string `json:"month" example:"https://example.com/api/v1/envelopes/45b6b5b9-f746-4ae9-b77b-7688b91f8166/YYYY-MM"` // This will always end in 'YYYY-MM' for clients to use replace with actual numbers.
 }
 
 // RegisterEnvelopeRoutes registers the routes for envelopes with

api/swagger.yaml

@@ -12,16 +12,16 @@ type Account struct {
 	Model
 	AccountCreate
 	Budget            Budget          `json:"-"`
-	Balance           decimal.Decimal `json:"balance" gorm:"-"`
-	ReconciledBalance decimal.Decimal `json:"reconciledBalance" gorm:"-"`
+	Balance           decimal.Decimal `json:"balance" gorm:"-" example:"2735.17"`
+	ReconciledBalance decimal.Decimal `json:"reconciledBalance" gorm:"-" example:"2539.57"`
 }
 
 type AccountCreate struct {
-	Name     string    `json:"name,omitempty" example:"Checking"`
-	Note     string    `json:"note,omitempty" example:"My bank account"`
+	Name     string    `json:"name,omitempty" example:"Cash" default:""`
+	Note     string    `json:"note,omitempty" example:"Money in my wallet" default:""`
 	BudgetID uuid.UUID `json:"budgetId" example:"550dc009-cea6-4c12-b2a5-03446eb7b7cf"`
-	OnBudget bool      `json:"onBudget" example:"false"` // Always false when external: true
-	External bool      `json:"external" example:"true"`
+	OnBudget bool      `json:"onBudget" example:"true" default:"false"` // Always false when external: true
+	External bool      `json:"external" example:"false" default:"false"`
 }
 
 func (a Account) WithCalculations() Account {

pkg/controllers/budget.go

@@ -13,8 +13,8 @@ type Allocation struct {
 }
 
 type AllocationCreate struct {
-	Month      uint8           `json:"month" gorm:"uniqueIndex:year_month;check:month_valid,month >= 1 AND month <= 12"`
-	Year       uint            `json:"year" gorm:"uniqueIndex:year_month"`
-	Amount     decimal.Decimal `json:"amount" gorm:"type:DECIMAL(20,8)"`
-	EnvelopeID uuid.UUID       `json:"envelopeId,omitempty"`
+	Month      uint8           `json:"month" gorm:"uniqueIndex:year_month;check:month_valid,month >= 1 AND month <= 12" minimum:"1" maximum:"12" example:"6"`
+	Year       uint            `json:"year" gorm:"uniqueIndex:year_month" example:"2022"`
+	Amount     decimal.Decimal `json:"amount" gorm:"type:DECIMAL(20,8)" example:"22.01" minimum:"0.00000001" maximum:"999999999999.99999999" multipleOf:"0.00000001"` // The maximum value is "999999999999.99999999", swagger unfortunately rounds this.
+	EnvelopeID uuid.UUID       `json:"envelopeId,omitempty" example:"a0909e84-e8f9-4cb6-82a5-025dff105ff2"`
 }

pkg/controllers/envelope.go

@@ -14,18 +14,18 @@ import (
 type Budget struct {
 	Model
 	BudgetCreate
-	Balance decimal.Decimal `json:"balance" gorm:"-"`
+	Balance decimal.Decimal `json:"balance" gorm:"-" example:"3423.42"`
 }
 
 type BudgetCreate struct {
-	Name     string `json:"name,omitempty" example:"My First Budget"`
-	Note     string `json:"note,omitempty" example:"A description so I remember what this was for"`
-	Currency string `json:"currency,omitempty" example:"€"`
+	Name     string `json:"name,omitempty" example:"Morre's Budget" default:""`
+	Note     string `json:"note,omitempty" example:"My personal expenses" default:""`
+	Currency string `json:"currency,omitempty" example:"€" default:""`
 }
 
 type BudgetMonth struct {
-	ID        uuid.UUID       `json:"id" example:"23"`
-	Name      string          `json:"name" example:"A test envelope"`
-	Month     time.Time       `json:"month" example:"2006-05-04T15:02:01.000000Z"`
+	ID        uuid.UUID       `json:"id" example:"1e777d24-3f5b-4c43-8000-04f65f895578"` // The ID of the Envelope
+	Name      string          `json:"name" example:"Groceries"`                          // The name of the Envelope
+	Month     time.Time       `json:"month" example:"2006-05-01T00:00:00.000000Z"`       // This is always set to 00:00 UTC on the first of the month.
 	Envelopes []EnvelopeMonth `json:"envelopes,omitempty"`
 }

pkg/models/account.go

@@ -10,7 +10,7 @@ type Category struct {
 }
 
 type CategoryCreate struct {
-	Name     string    `json:"name,omitempty"`
-	BudgetID uuid.UUID `json:"budgetId"`
-	Note     string    `json:"note,omitempty"`
+	Name     string    `json:"name,omitempty" example:"Saving" default:""`
+	BudgetID uuid.UUID `json:"budgetId" example:"52d967d3-33f4-4b04-9ba7-772e5ab9d0ce"`
+	Note     string    `json:"note,omitempty" example:"All envelopes for long-term saving" default:""`
 }

pkg/models/allocation.go

@@ -16,19 +16,19 @@ type Envelope struct {
 }
 
 type EnvelopeCreate struct {
-	Name       string    `json:"name,omitempty"`
-	CategoryID uuid.UUID `json:"categoryId"`
-	Note       string    `json:"note,omitempty"`
+	Name       string    `json:"name,omitempty" example:"Groceries" default:""`
+	CategoryID uuid.UUID `json:"categoryId" example:"878c831f-af99-4a71-b3ca-80deb7d793c1"`
+	Note       string    `json:"note,omitempty" example:"For stuff bought at supermarkets and drugstores" default:""`
 }
 
 // EnvelopeMonth contains data about an Envelope for a specific month.
 type EnvelopeMonth struct {
-	ID         uuid.UUID       `json:"id"`
-	Name       string          `json:"name"`
-	Month      time.Time       `json:"month"`
-	Spent      decimal.Decimal `json:"spent"`
-	Balance    decimal.Decimal `json:"balance"`
-	Allocation decimal.Decimal `json:"allocation"`
+	ID         uuid.UUID       `json:"id" example:"10b9705d-3356-459e-9d5a-28d42a6c4547"` // The ID of the Envelope
+	Name       string          `json:"name" example:"Groceries"`                          // The name of the Envelope
+	Month      time.Time       `json:"month" example:"1969-06-01T00:00:00.000000Z"`       // This is always set to 00:00 UTC on the first of the month.
+	Spent      decimal.Decimal `json:"spent" example:"73.12"`
+	Balance    decimal.Decimal `json:"balance" example:"12.32"`
+	Allocation decimal.Decimal `json:"allocation" example:"85.44"`
 }
 
 // Spent returns the amount spent for the month the time.Time instance is in.