vikunja-api/docs/content/doc/practical-instructions/swagger-docs.md
konrad b0d4902406 Make sure all int64 db fields are using bigint when actually storing the data ()
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>
2020-12-18 16:51:22 +00:00

1.7 KiB

date title draft type menu
2019-02-12:00:00+02:00 Modifying swagger api docs false doc
sidebar
parent
practical instructions

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 >}}