Skip to content

Commit 807501d

Browse files
morremeyermorremeyer
authored
docs: add examples for errors (#844)
1 parent 6b5b9dc commit 807501d

File tree

5 files changed

+46
-25
lines changed

5 files changed

+46
-25
lines changed

‎api/docs.go‎

Lines changed: 14 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4972,19 +4972,23 @@ const docTemplate = `{
49724972
"properties": {
49734973
"count": {
49744974
"description": "The amount of records returned in this response",
4975-
"type": "integer"
4975+
"type": "integer",
4976+
"example": 25
49764977
},
49774978
"limit": {
49784979
"description": "The maximum amount of resources to return for this request",
4979-
"type": "integer"
4980+
"type": "integer",
4981+
"example": 25
49804982
},
49814983
"offset": {
49824984
"description": "The offset for the first record returned",
4983-
"type": "integer"
4985+
"type": "integer",
4986+
"example": 50
49844987
},
49854988
"total": {
49864989
"description": "The total number of resources matching the query",
4987-
"type": "integer"
4990+
"type": "integer",
4991+
"example": 827
49884992
}
49894993
}
49904994
},
@@ -5163,7 +5167,8 @@ const docTemplate = `{
51635167
},
51645168
"error": {
51655169
"description": "The error, if any occurred",
5166-
"type": "string"
5170+
"type": "string",
5171+
"example": "the specified resource ID is not a valid UUID"
51675172
}
51685173
}
51695174
},
@@ -5191,7 +5196,8 @@ const docTemplate = `{
51915196
},
51925197
"error": {
51935198
"description": "The error, if any occurred",
5194-
"type": "string"
5199+
"type": "string",
5200+
"example": "the specified resource ID is not a valid UUID"
51955201
},
51965202
"pagination": {
51975203
"description": "Pagination information",
@@ -5229,7 +5235,8 @@ const docTemplate = `{
52295235
},
52305236
"error": {
52315237
"description": "The error, if any occurred for this transaction",
5232-
"type": "string"
5238+
"type": "string",
5239+
"example": "the specified resource ID is not a valid UUID"
52335240
}
52345241
}
52355242
},

‎api/swagger.json‎

Lines changed: 14 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4961,19 +4961,23 @@
49614961
"properties": {
49624962
"count": {
49634963
"description": "The amount of records returned in this response",
4964-
"type": "integer"
4964+
"type": "integer",
4965+
"example": 25
49654966
},
49664967
"limit": {
49674968
"description": "The maximum amount of resources to return for this request",
4968-
"type": "integer"
4969+
"type": "integer",
4970+
"example": 25
49694971
},
49704972
"offset": {
49714973
"description": "The offset for the first record returned",
4972-
"type": "integer"
4974+
"type": "integer",
4975+
"example": 50
49734976
},
49744977
"total": {
49754978
"description": "The total number of resources matching the query",
4976-
"type": "integer"
4979+
"type": "integer",
4980+
"example": 827
49774981
}
49784982
}
49794983
},
@@ -5152,7 +5156,8 @@
51525156
},
51535157
"error": {
51545158
"description": "The error, if any occurred",
5155-
"type": "string"
5159+
"type": "string",
5160+
"example": "the specified resource ID is not a valid UUID"
51565161
}
51575162
}
51585163
},
@@ -5180,7 +5185,8 @@
51805185
},
51815186
"error": {
51825187
"description": "The error, if any occurred",
5183-
"type": "string"
5188+
"type": "string",
5189+
"example": "the specified resource ID is not a valid UUID"
51845190
},
51855191
"pagination": {
51865192
"description": "Pagination information",
@@ -5218,7 +5224,8 @@
52185224
},
52195225
"error": {
52205226
"description": "The error, if any occurred for this transaction",
5221-
"type": "string"
5227+
"type": "string",
5228+
"example": "the specified resource ID is not a valid UUID"
52225229
}
52235230
}
52245231
},

‎api/swagger.yaml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -535,15 +535,19 @@ definitions:
535535
properties:
536536
count:
537537
description: The amount of records returned in this response
538+
example: 25
538539
type: integer
539540
limit:
540541
description: The maximum amount of resources to return for this request
542+
example: 25
541543
type: integer
542544
offset:
543545
description: The offset for the first record returned
546+
example: 50
544547
type: integer
545548
total:
546549
description: The total number of resources matching the query
550+
example: 827
547551
type: integer
548552
type: object
549553
controllers.RenameRuleListResponse:
@@ -679,6 +683,7 @@ definitions:
679683
type: array
680684
error:
681685
description: The error, if any occurred
686+
example: the specified resource ID is not a valid UUID
682687
type: string
683688
type: object
684689
controllers.TransactionListResponse:
@@ -698,6 +703,7 @@ definitions:
698703
type: array
699704
error:
700705
description: The error, if any occurred
706+
example: the specified resource ID is not a valid UUID
701707
type: string
702708
pagination:
703709
allOf:
@@ -719,6 +725,7 @@ definitions:
719725
description: The transaction data, if creation was successful
720726
error:
721727
description: The error, if any occurred for this transaction
728+
example: the specified resource ID is not a valid UUID
722729
type: string
723730
type: object
724731
controllers.TransactionV2:

‎pkg/controllers/responses.go‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,8 @@ type ResponseMatchRule struct {
1515

1616
// Pagination contains information about the pagination for collection endpoint responses.
1717
type Pagination struct {
18-
Count int `json:"count"` // The amount of records returned in this response
19-
Offset uint `json:"offset"` // The offset for the first record returned
20-
Limit int `json:"limit"` // The maximum amount of resources to return for this request
21-
Total int64 `json:"total"` // The total number of resources matching the query
18+
Count int `json:"count" example:"25"` // The amount of records returned in this response
19+
Offset uint `json:"offset" example:"50"` // The offset for the first record returned
20+
Limit int `json:"limit" example:"25"` // The maximum amount of resources to return for this request
21+
Total int64 `json:"total" example:"827"` // The total number of resources matching the query
2222
}

‎pkg/controllers/transaction_v3.go‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -17,19 +17,19 @@ import (
1717
)
1818

1919
type TransactionListResponseV3 struct {
20-
Data []TransactionV3 `json:"data"` // List of transactions
21-
Error *string `json:"error"` // The error, if any occurred
22-
Pagination *Pagination `json:"pagination"` // Pagination information
20+
Data []TransactionV3 `json:"data"` // List of transactions
21+
Error *string `json:"error" example:"the specified resource ID is not a valid UUID"` // The error, if any occurred
22+
Pagination *Pagination `json:"pagination"` // Pagination information
2323
}
2424

2525
type TransactionCreateResponseV3 struct {
26-
Error *string `json:"error"` // The error, if any occurred
27-
Data []TransactionResponseV3 `json:"data"` // List of created transactions
26+
Error *string `json:"error" example:"the specified resource ID is not a valid UUID"` // The error, if any occurred
27+
Data []TransactionResponseV3 `json:"data"` // List of created transactions
2828
}
2929

3030
type TransactionResponseV3 struct {
31-
Error *string `json:"error"` // The error, if any occurred for this transaction
32-
Data *TransactionV3 `json:"data"` // The transaction data, if creation was successful
31+
Error *string `json:"error" example:"the specified resource ID is not a valid UUID"` // The error, if any occurred for this transaction
32+
Data *TransactionV3 `json:"data"` // The transaction data, if creation was successful
3333
}
3434

3535
// TransactionV3 is the representation of a Transaction in API v3.

0 commit comments

Comments
 (0)