Commit b3110c3a authored by zauberstuhl's avatar zauberstuhl

Add apidoc documentation to controllers

parent 42687d75
docs/
package-lock.json
GangGo Restful API Library
--------------------------
# GangGo API Library
## Documentation
If you want to write an application for GangGo checkout our [API documentation page](https://ganggo.github.io/api/index.html).
### Generate
Download and install apidoc via:
npm install apidoc -g
Then run in the api repository:
apidoc -i app -o <docs-path>
......@@ -3,5 +3,11 @@
"version": "0.0.0",
"description": "GangGo API Library",
"title": "API Documentation",
"url" : "/api/v0"
"url": "/api/v0",
"header": {
"filename": "docs/header.md"
},
"footer": {
"filename": "docs/footer.md"
}
}
......@@ -24,12 +24,56 @@ import (
"errors"
)
/**
* @apiDefine Aspects Aspects endpoint
*
* Viewing, creating and deleting Aspect structures
*/
type ApiAspect struct {
*revel.Controller
ApiHelper
}
/**
* @api {get} /people/:id/aspects Display aspects which Person is included in
* @apiName ApiAspect.ShowPerson
* @apiGroup Aspects
*
* @apiParam {Number} id Person database ID
* @apiParam {String} access_token Oauth access token
*
* @apiSuccess {String} CreatedAt Timestamp of creation
* @apiSuccess {String} UpdatedAt Timestamp of last replacment
* @apiSuccess {String} Guid Unique global ID
* @apiSuccess {Number} ID Unique database ID
* @apiSuccess {String} Name Aspect name
* @apiSuccess {Number} UserID User database ID
* @apiSuccess {Boolean} Default Default aspect
* @apiSuccess {Array} Memberships Aspect memberships
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* [
* {
* "ID": 1,
* "CreatedAt": "2017-12-20T00:02:10Z",
* "UpdatedAt": "2017-12-20T00:02:10Z",
* "Name": "Friends",
* "UserID": 1,
* "Default": false,
* "Memberships": [...]
* }
* ]
*
* @apiError error Contains recent error message
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "Error 1052: Column 'xyz' not found"
* }
*/
func (a ApiAspect) ShowPerson() revel.Result {
var (
personID uint
......@@ -52,6 +96,41 @@ func (a ApiAspect) ShowPerson() revel.Result {
return a.RenderJSON(aspects)
}
/**
* @api {post} /people/:id/aspects/:aspect_id Add person to aspect
* @apiName ApiAspect.CreatePerson
* @apiGroup Aspects
*
* @apiParam {Number} id Person database ID
* @apiParam {Number} aspect_id Aspect database ID
* @apiParam {String} access_token Oauth access token
*
* @apiSuccess {String} CreatedAt Timestamp of creation
* @apiSuccess {String} UpdatedAt Timestamp of last replacment
* @apiSuccess {Number} ID Unique database ID
* @apiSuccess {Number} AspectID Aspect database ID
* @apiSuccess {Number} PersonID Person database ID
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* [
* {
* "ID": 1,
* "CreatedAt": "2017-12-20T00:02:10Z",
* "UpdatedAt": "2017-12-20T00:02:10Z",
* "AspectID": 1,
* "PersonID": 1
* }
* ]
*
* @apiError error Contains recent error message
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "Error 1052: Column 'xyz' not found"
* }
*/
func (a ApiAspect) CreatePerson() revel.Result {
var personID, aspectID uint
......@@ -72,6 +151,41 @@ func (a ApiAspect) CreatePerson() revel.Result {
return a.RenderJSON(membership)
}
/**
* @api {delete} /people/:id/aspects/:aspect_id Delete person from aspect
* @apiName ApiAspect.DeletePerson
* @apiGroup Aspects
*
* @apiParam {Number} id Person database ID
* @apiParam {Number} aspect_id Aspect database ID
* @apiParam {String} access_token Oauth access token
*
* @apiSuccess {String} CreatedAt Timestamp of creation
* @apiSuccess {String} UpdatedAt Timestamp of last replacment
* @apiSuccess {Number} ID Unique database ID
* @apiSuccess {Number} AspectID Aspect database ID
* @apiSuccess {Number} PersonID Person database ID
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* [
* {
* "ID": 1,
* "CreatedAt": "2017-12-20T00:02:10Z",
* "UpdatedAt": "2017-12-20T00:02:10Z",
* "AspectID": 1,
* "PersonID": 1
* }
* ]
*
* @apiError error Contains recent error message
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "Error 1052: Column 'xyz' not found"
* }
*/
func (a ApiAspect) DeletePerson() revel.Result {
var personID, aspectID uint
......@@ -103,6 +217,43 @@ func (a ApiAspect) Index(fields string) revel.Result {
helpers.SelectStructFields(user.Aspects, fields))
}
/**
* @api {post} /aspects Create new aspect
* @apiName ApiAspect.Create
* @apiGroup Aspects
*
* @apiParam {String} aspect_name Aspect name
* @apiParam {String} access_token Oauth access token
*
* @apiSuccess {String} CreatedAt Timestamp of creation
* @apiSuccess {String} UpdatedAt Timestamp of last replacment
* @apiSuccess {String} Guid Unique global ID
* @apiSuccess {Number} ID Unique database ID
* @apiSuccess {String} Name Aspect name
* @apiSuccess {Number} UserID User database ID
* @apiSuccess {Boolean} Default Default aspect
* @apiSuccess {Array} Memberships Aspect memberships
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "ID": 1,
* "CreatedAt": "2017-12-20T00:02:10Z",
* "UpdatedAt": "2017-12-20T00:02:10Z",
* "Name": "Friends",
* "UserID": 1,
* "Default": false,
* "Memberships": [...]
* }
*
* @apiError error Contains recent error message
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "Error 1052: Column 'xyz' not found"
* }
*/
func (a ApiAspect) Create() revel.Result {
name := a.Params.Get("aspect_name")
if name == "" {
......
......@@ -24,12 +24,61 @@ import (
federation "gopkg.in/ganggo/federation.v0"
)
/**
* @apiDefine Comments Comments endpoint
*
* Viewing, creating and deleting Comment structures
*/
type ApiComment struct {
*revel.Controller
ApiHelper
}
/**
* @api {get} /posts/:id/comments Display comments related to post
* @apiName ApiComment.Index
* @apiGroup Comments
*
* @apiParam {Number} id Post database ID
* @apiParam {String} access_token Oauth access token
*
* @apiSuccess {String} CreatedAt Timestamp of creation
* @apiSuccess {String} UpdatedAt Timestamp of last replacment
* @apiSuccess {String} Guid Unique global ID
* @apiSuccess {Number} ID Unique database ID
* @apiSuccess {String} Text Status message
* @apiSuccess {Number} ShareableID Post database ID
* @apiSuccess {Number} PersonID Person database ID
* @apiSuccess {String} ShareableType Shareable type e.g. Post, Comment
* @apiSuccess {Hash} CommentSignature Signature
* @apiSuccess {Hash} Person Person structure
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* [
* {
* "ID": 12,
* "CreatedAt": "2018-01-08T15:25:43Z",
* "UpdatedAt": "2018-01-08T15:25:43Z",
* "Text": "hi",
* "ShareableID": 20,
* "PersonID": 1,
* "Guid": "cc783a9749f09c7d817a1707a4c052bc",
* "LikesCount": 0,
* "ShareableType": "Post",
* [...]
* }
* ]
*
* @apiError error Contains recent error message
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "Error 1052: Column 'xyz' not found"
* }
*/
func (c ApiComment) Index() revel.Result {
var (
postID uint
......@@ -45,6 +94,24 @@ func (c ApiComment) Index() revel.Result {
return c.RenderJSON(comments)
}
/**
* @api {post} /posts/:id/comments Create comment on post
* @apiName ApiComment.Create
* @apiGroup Comments
*
* @apiParam {Number} id Post database ID
* @apiParam {String} comment Status message
* @apiParam {String} [fields] Display only specific fields, e.g. fields=ID,Person(ID:Profile(ID:ImageUrl))
* @apiParam {String} access_token Oauth access token
*
* @apiError error Contains recent error message
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "Error 1052: Column 'xyz' not found"
* }
*/
func (c ApiComment) Create() revel.Result {
var (
comment, fields string
......
......@@ -25,12 +25,60 @@ import (
federation "gopkg.in/ganggo/federation.v0"
)
/**
* @apiDefine Likes Likes endpoint
*
* Viewing, creating and deleting Like structures
*/
type ApiLike struct {
*revel.Controller
ApiHelper
}
/**
* @api {get} /posts/:id/likes Display likes related to post
* @apiName ApiLike.Index
* @apiGroup Likes
*
* @apiParam {Number} id Post database ID
* @apiParam {String} access_token Oauth access token
*
* @apiSuccess {String} CreatedAt Timestamp of creation
* @apiSuccess {String} UpdatedAt Timestamp of last replacment
* @apiSuccess {String} Guid Unique global ID
* @apiSuccess {Number} ID Unique database ID
* @apiSuccess {Boolean} Positive Like or dis-like
* @apiSuccess {Number} TargetID Post database ID
* @apiSuccess {Number} PersonID Person database ID
* @apiSuccess {String} AuthorSignature Signature
* @apiSuccess {String} TargetType Entity type e.g. Post, Comment
* @apiSuccess {Hash} Signature Signature structure
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* [
* {
* "ID": 12,
* "CreatedAt": "2018-01-08T15:25:43Z",
* "UpdatedAt": "2018-01-08T15:25:43Z",
* "TargetID": 20,
* "PersonID": 1,
* "Positive": true,
* "Guid": "cc783a9749f09c7d817a1707a4c052bc",
* "TargetType": "Post",
* [...]
* }
* ]
*
* @apiError error Contains recent error message
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "Error 1052: Column 'xyz' not found"
* }
*/
func (l ApiLike) Index() revel.Result {
var (
postID uint
......@@ -47,6 +95,48 @@ func (l ApiLike) Index() revel.Result {
return l.RenderJSON(likes)
}
/**
* @api {post} /posts/:id/likes Create a like
* @apiName ApiLike.Create
* @apiGroup Likes
*
* @apiParam {Number} id Post database ID
* @apiParam {Boolean} positive Like or dis-like
* @apiParam {String} access_token Oauth access token
*
* @apiSuccess {String} CreatedAt Timestamp of creation
* @apiSuccess {String} UpdatedAt Timestamp of last replacment
* @apiSuccess {String} Guid Unique global ID
* @apiSuccess {Number} ID Unique database ID
* @apiSuccess {Boolean} Positive Like or dis-like
* @apiSuccess {Number} TargetID Post database ID
* @apiSuccess {Number} PersonID Person database ID
* @apiSuccess {String} AuthorSignature Signature
* @apiSuccess {String} TargetType Entity type e.g. Post, Comment
* @apiSuccess {Hash} Signature Signature structure
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "ID": 12,
* "CreatedAt": "2018-01-08T15:25:43Z",
* "UpdatedAt": "2018-01-08T15:25:43Z",
* "TargetID": 20,
* "PersonID": 1,
* "Positive": true,
* "Guid": "cc783a9749f09c7d817a1707a4c052bc",
* "TargetType": "Post",
* [...]
* }
*
* @apiError error Contains recent error message
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "Error 1052: Column 'xyz' not found"
* }
*/
func (l ApiLike) Create() revel.Result {
var (
postID uint
......
......@@ -22,12 +22,56 @@ import (
"gopkg.in/ganggo/ganggo.v0/app/models"
)
/**
* @apiDefine Notifications Notifications endpoint
*
* Viewing, creating and deleting Notification structures
*/
type ApiNotification struct {
*revel.Controller
ApiHelper
}
/**
* @api {get} /notifications Display notifications
* @apiName ApiNotification.Index
* @apiGroup Notifications
*
* @apiParam {String} access_token Oauth access token
*
* @apiSuccess {String} CreatedAt Timestamp of creation
* @apiSuccess {String} UpdatedAt Timestamp of last replacment
* @apiSuccess {Number} ID Unique database ID
* @apiSuccess {Boolean} Unread If the notification is un-read
* @apiSuccess {String} TargetGuid Entity global ID
* @apiSuccess {String} TargetType Entity type e.g. Post, Comment
* @apiSuccess {Number} PersonID Person database ID
* @apiSuccess {Number} UserID User database ID
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* [
* {
* "ID": 12,
* "CreatedAt": "2018-01-08T15:25:43Z",
* "UpdatedAt": "2018-01-08T15:25:43Z",
* "TargetGuid": "cc783a9749f09c7d817a1707a4c052bc",
* "PersonID": 1,
* "UserID": 2,
* "Unread": true,
* "TargetType": "Post"
* }
* ]
*
* @apiError error Contains recent error message
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "Error 1052: Column 'xyz' not found"
* }
*/
func (n ApiNotification) Index() revel.Result {
user, err := models.CurrentUser(n.Params, n.Session)
if err != nil {
......@@ -53,6 +97,44 @@ func (n ApiNotification) Show() revel.Result {
return n.NotFound("Not implemented yet")
}
/**
* @api {put} /notifications/:id Set notification read
* @apiName ApiNotification.Update
* @apiGroup Notifications
*
* @apiParam {Number} id Notification database ID
* @apiParam {String} access_token Oauth access token
*
* @apiSuccess {String} CreatedAt Timestamp of creation
* @apiSuccess {String} UpdatedAt Timestamp of last replacment
* @apiSuccess {Number} ID Unique database ID
* @apiSuccess {Boolean} Unread If the notification is un-read
* @apiSuccess {String} TargetGuid Entity global ID
* @apiSuccess {String} TargetType Entity type e.g. Post, Comment
* @apiSuccess {Number} PersonID Person database ID
* @apiSuccess {Number} UserID User database ID
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "ID": 12,
* "CreatedAt": "2018-01-08T15:25:43Z",
* "UpdatedAt": "2018-01-08T15:25:43Z",
* "TargetGuid": "cc783a9749f09c7d817a1707a4c052bc",
* "PersonID": 1,
* "UserID": 2,
* "Unread": false,
* "TargetType": "Post"
* }
*
* @apiError error Contains recent error message
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "Error 1052: Column 'xyz' not found"
* }
*/
func (n ApiNotification) Update(id uint) revel.Result {
user, err := models.CurrentUser(n.Params, n.Session)
if err != nil {
......
......@@ -32,15 +32,41 @@ type TokenResult struct {
// it checks on interface nil value
type TokenString string
/**
* @apiDefine Oauth Oauth endpoint
*
* Create and delete oauth tokens
*/
type ApiOAuth struct {
*revel.Controller
}
// Basic password credentials flow
// /token?grant_type=password&username=USERNAME&password=PASSWORD&client_id=CLIENT_ID
//
// If the password and username are correct
// the application is authorized and it will return an access token
/**
* @api {post} /oauth/tokens Create/Fetch token
* @apiName ApiOAuth.Create
* @apiGroup Oauth
*
* @apiParam {String} grant_type Grant type
* @apiParam {String} username Username
* @apiParam {String} password Password
* @apiParam {String} client_id Client name e.g. android_appXYZ
*
* @apiSuccess {String} token Access token
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "token": "5b5d5b4f7044e3444db73504e8b08be8"
* }
*
* @apiError error Contains recent error message
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "Error 1052: Column 'xyz' not found"
* }
*/
func (o ApiOAuth) Create() revel.Result {
var (
grantType string
......@@ -113,6 +139,27 @@ func (o ApiOAuth) Create() revel.Result {
})
}
/**
* @api {delete} /oauth/tokens/:id Delete token
* @apiName ApiOAuth.Delete
* @apiGroup Oauth
*
* @apiParam {Number} id Token database ID
*
* @apiSuccess {String} token Access token
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {}
*
* @apiError error Contains recent error message
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "Error 1052: Column 'xyz' not found"
* }
*/
func (o ApiOAuth) Delete(id uint) revel.Result {
token := models.OAuthToken{ID: id}
user, err := models.CurrentUser(o.Params, o.Session)
......
......@@ -22,6 +22,11 @@ import (
"gopkg.in/ganggo/ganggo.v0/app/models"
)
/**
* @apiDefine People People endpoint
*
* Viewing, creating and deleting Person structures
*/
type ApiPeople struct {
*revel.Controller
......@@ -36,6 +41,42 @@ func (p ApiPeople) Create() revel.Result {
return p.NotFound("Not implemented yet")
}
/**
* @api {get} /people/:id Display a specific person
* @apiName ApiPeople.Show
* @apiGroup People
*
* @apiParam {String} id Person database ID
* @apiParam {String} access_token Oauth access token
*
* @apiSuccess {String} CreatedAt Timestamp of creation
* @apiSuccess {String} UpdatedAt Timestamp of last replacment
* @apiSuccess {Number} ID Unique database ID
* @apiSuccess {String} Guid Person global ID
* @apiSuccess {String} Author Handle with TLD
* @apiSuccess {String} SerializedPublicKey Public key
* @apiSuccess {Number} UserID User database ID (null if not a local user)
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "ID": 12,
* "CreatedAt": "2018-01-08T15:25:43Z",
* "UpdatedAt": "2018-01-08T15:25:43Z",
* "Guid": "cc783a9749f09c7d817a1707a4c052bc",
* "Author": "test@localhost",
* "SerializedPublicKey": "[...]",
* "UserID": 1,
* }
*
* @apiError error Contains recent error message
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "Error 1052: Column 'xyz' not found"
* }
*/
func (p ApiPeople) Show() revel.Result {
var (
personID uint
......
......@@ -30,12 +30,57 @@ import (
federation "gopkg.in/ganggo/federation.v0"
)
/**
* @apiDefine Posts Posts endpoint
*
* Viewing, creating and deleting Post structures
*/
type ApiPost struct {
*revel.Controller
ApiHelper
}
/**
* @api {get} /posts Fetch all posts
* @apiName ApiPost.Index
* @apiGroup Posts
*
* @apiParam {String} access_token Oauth access token
* @apiParam {Number} [offset] Post offset for database
* @apiParam {String} [fields] Display only specific fields, e.g. fields=ID,Person(ID:Profile(ID:ImageUrl))
* @apiParam {Number} [visibility] 0 = all posts, 1 = public posts, 2 private posts
*
* @apiSuccess {Array} Comments Comments related to the post