forked from vikunja/vikunja
konrad
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: vikunja/api#741 Co-Authored-By: konrad <konrad@kola-entertainments.de> Co-Committed-By: konrad <konrad@kola-entertainments.de>
48 lines
1.7 KiB
Markdown
48 lines
1.7 KiB
Markdown
---
|
|
date: "2019-02-12:00:00+02:00"
|
|
title: "Modifying swagger api docs"
|
|
draft: false
|
|
type: "doc"
|
|
menu:
|
|
sidebar:
|
|
parent: "practical instructions"
|
|
---
|
|
|
|
# Adding/editing swagger api docs
|
|
|
|
The api documentation is generated using [swaggo](https://github.com/swaggo/swag) 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 >}}
|