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:"int(11) 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:"int(11) INDEX" json:"-"`
|
||
|
|
NamespaceID int64 `xorm:"int(11) 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 >}}
|