b0d4902406
Fix lint Fix migration query for postgres Fix migration statements Add migration to make all int(11) fields bigint by default Make all int(11) fields bigint by default Co-authored-by: kolaente <k@knt.li> Reviewed-on: https://kolaente.dev/vikunja/api/pulls/741 Co-Authored-By: konrad <konrad@kola-entertainments.de> Co-Committed-By: konrad <konrad@kola-entertainments.de>
1.7 KiB
| date | title | draft | type | menu | ||||
|---|---|---|---|---|---|---|---|---|
| 2019-02-12:00:00+02:00 | Modifying swagger api docs | false | doc |
|
Adding/editing swagger api docs
The api documentation is generated using swaggo from comments.
Documenting structs
You should always comment every field which will be exposed as a json in the api. These comments will show up in the documentation, it'll make it easier for developers using the api.
As an example, this is the definition of a list with all comments:
{{< highlight golang >}}
// List represents a list of tasks
type List struct {
// The unique, numeric id of this list.
ID int64 xorm:"bigint autoincr not null unique pk" json:"id" param:"list"
// The title of the list. You'll see this in the namespace overview.
Title string xorm:"varchar(250)" json:"title" valid:"required,runelength(3|250)" minLength:"3" maxLength:"250"
// The description of the list.
Description string xorm:"varchar(1000)" json:"description" valid:"runelength(0|1000)" maxLength:"1000"
OwnerID int64 xorm:"bigint INDEX" json:"-"
NamespaceID int64 xorm:"bigint INDEX" json:"-" param:"namespace"
// The user who created this list.
Owner User `xorm:"-" json:"owner" valid:"-"`
// An array of tasks which belong to the list.
Tasks []*ListTask `xorm:"-" json:"tasks"`
// A unix timestamp when this list was created. You cannot change this value.
Created int64 `xorm:"created" json:"created"`
// A unix timestamp when this list was last updated. You cannot change this value.
Updated int64 `xorm:"updated" json:"updated"`
web.CRUDable `xorm:"-" json:"-"`
web.Rights `xorm:"-" json:"-"`
} {{< /highlight >}}