Add swagger descriptions and needed structs (gogs#53)

* Add swagger descriptions and needed structs

* Remove missed TODO comment

Author: sapk

gitea/miscellaneous.go

@@ -4,15 +4,47 @@
 
 package gitea
 
+// SearchResults results of search
+// swagger:response SearchResults
+type SearchResults struct {
+	OK   bool          `json:"ok"`
+	Data []*Repository `json:"data"`
+}
+
+// SearchError error of failing search
+// swagger:response SearchError
+type SearchError struct {
+	OK    bool   `json:"ok"`
+	Error string `json:"error"`
+}
+
 // MarkdownOption markdown options
+// swagger:parameters renderMarkdown
 type MarkdownOption struct {
-	Text    string
-	Mode    string
+	// Text markdown to render
+	//
+	// in: body
+	Text string
+	// Mode to render
+	//
+	// in: body
+	Mode string
+	// Context to render
+	//
+	// in: body
 	Context string
-	Wiki    bool
+	// Is it a wiki page ?
+	//
+	// in: body
+	Wiki bool
 }
 
+// MarkdownRender is a rendered markdown document
+// swagger:response MarkdownRender
+type MarkdownRender string
+
 // ServerVersion wraps the version of the server
+// swagger:response ServerVersion
 type ServerVersion struct {
 	Version string
 }

gitea/repo.go

@@ -19,6 +19,7 @@ type Permission struct {
 }
 
 // Repository represents a API repository.
+// swagger:response Repository
 type Repository struct {
 	ID            int64       `json:"id"`
 	Owner         *User       `json:"owner"`
@@ -42,6 +43,10 @@ type Repository struct {
 	Permissions   *Permission `json:"permissions,omitempty"`
 }
 
+// RepositoryList represents a list of API repository.
+// swagger:response RepositoryList
+type RepositoryList []*Repository
+
 // ListMyRepos lists all repositories for the authenticated user that has access to.
 func (c *Client) ListMyRepos() ([]*Repository, error) {
 	repos := make([]*Repository, 0, 10)
@@ -61,14 +66,37 @@ func (c *Client) ListOrgRepos(org string) ([]*Repository, error) {
 }
 
 // CreateRepoOption options when creating repository
+//swagger:parameters createOrgRepo
 type CreateRepoOption struct {
-	Name        string `json:"name" binding:"Required;AlphaDashDot;MaxSize(100)"`
+	// Name of the repository to create
+	//
+	// in: body
+	// unique: true
+	Name string `json:"name" binding:"Required;AlphaDashDot;MaxSize(100)"`
+	// Description of the repository to create
+	//
+	// in: body
 	Description string `json:"description" binding:"MaxSize(255)"`
-	Private     bool   `json:"private"`
-	AutoInit    bool   `json:"auto_init"`
-	Gitignores  string `json:"gitignores"`
-	License     string `json:"license"`
-	Readme      string `json:"readme"`
+	// Is the repository to create private ?
+	//
+	// in: body
+	Private bool `json:"private"`
+	// Init the repository to create ?
+	//
+	// in: body
+	AutoInit bool `json:"auto_init"`
+	// Gitignores to use
+	//
+	// in: body
+	Gitignores string `json:"gitignores"`
+	// License to use
+	//
+	// in: body
+	License string `json:"license"`
+	// Readme of the repository to create
+	//
+	// in: body
+	Readme string `json:"readme"`
 }
 
 // CreateRepo creates a repository for authenticated user.

gitea/repo_key.go

@@ -34,9 +34,20 @@ func (c *Client) GetDeployKey(user, repo string, keyID int64) (*DeployKey, error
 }
 
 // CreateKeyOption options when create deploy key
+// swagger:parameters userCurrentPostKey
 type CreateKeyOption struct {
+	// Title of the key to add
+	//
+	// in: body
+	// required: true
+	// unique: true
 	Title string `json:"title" binding:"Required"`
-	Key   string `json:"key" binding:"Required"`
+	// An armored SSH key to add
+	//
+	// in: body
+	// required: true
+	// unique: true
+	Key string `json:"key" binding:"Required"`
 }
 
 // CreateDeployKey options when create one deploy key

gitea/repo_watch.go

@@ -11,6 +11,7 @@ import (
 )
 
 // WatchInfo represents a API watch status of one repository
+// swagger:response WatchInfo
 type WatchInfo struct {
 	Subscribed    bool        `json:"subscribed"`
 	Ignored       bool        `json:"ignored"`

gitea/user.go

@@ -10,6 +10,7 @@ import (
 )
 
 // User represents a API user.
+// swagger:response User
 type User struct {
 	ID        int64  `json:"id"`
 	UserName  string `json:"login"`
@@ -18,6 +19,10 @@ type User struct {
 	AvatarURL string `json:"avatar_url"`
 }
 
+// UserList represents a list of API user.
+// swagger:response UserList
+type UserList []*User
+
 // MarshalJSON implements the json.Marshaler interface for User, adding field(s) for backward compatibility
 func (u User) MarshalJSON() ([]byte, error) {
 	// Re-declaring User to avoid recursion

gitea/user_app.go

@@ -18,11 +18,16 @@ func BasicAuthEncode(user, pass string) string {
 }
 
 // AccessToken represents a API access token.
+// swagger:response AccessToken
 type AccessToken struct {
 	Name string `json:"name"`
 	Sha1 string `json:"sha1"`
 }
 
+// AccessTokenList represents a list of API access token.
+// swagger:response AccessTokenList
+type AccessTokenList []*AccessToken 
+
 // ListAccessTokens lista all the access tokens of user
 func (c *Client) ListAccessTokens(user, pass string) ([]*AccessToken, error) {
 	tokens := make([]*AccessToken, 0, 10)
@@ -31,6 +36,7 @@ func (c *Client) ListAccessTokens(user, pass string) ([]*AccessToken, error) {
 }
 
 // CreateAccessTokenOption options when create access token
+// swagger:parameters userCreateToken
 type CreateAccessTokenOption struct {
 	Name string `json:"name" binding:"Required"`
 }

gitea/user_gpgkey.go

@@ -11,7 +11,12 @@ import (
 	"time"
 )
 
+// GPGKeyList represents a list of GPGKey
+// swagger:response GPGKeyList
+type GPGKeyList []*GPGKey
+
 // GPGKey a user GPG key to sign commit and tag in repository
+// swagger:response GPGKey
 type GPGKey struct {
 	ID                int64          `json:"id"`
 	PrimaryKeyID      string         `json:"primary_key_id"`
@@ -28,13 +33,20 @@ type GPGKey struct {
 }
 
 // GPGKeyEmail a email attache to a GPGKey
+// swagger:model GPGKeyEmail
 type GPGKeyEmail struct {
 	Email    string `json:"email"`
 	Verified bool   `json:"verified"`
 }
 
 // CreateGPGKeyOption options create user GPG key
+// swagger:parameters userCurrentPostGPGKey
 type CreateGPGKeyOption struct {
+	// An armored GPG key to add
+	//
+	// in: body
+	// required: true
+	// unique: true
 	ArmoredKey string `json:"armored_public_key" binding:"Required"`
 }
 

gitea/user_key.go

@@ -11,7 +11,12 @@ import (
 	"time"
 )
 
+// PublicKeyList represents a list of PublicKey
+// swagger:response PublicKeyList
+type PublicKeyList []*PublicKey
+
 // PublicKey publickey is a user key to push code to repository
+// swagger:response PublicKey
 type PublicKey struct {
 	ID      int64     `json:"id"`
 	Key     string    `json:"key"`