DeforaNetworks/corteza
3
0
Fork 0
Code Activity

restructure docs

Browse Source
This commit is contained in:
Tit Petric
2018-06-03 15:03:07 +02:00
parent a002322697
commit 4d119ded7b
11 changed files with 139 additions and 179 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/README.md
+42 -54
View File
@@ -8,7 +8,7 @@ Organisations represent a top-level grouping entity. There may be many organisat
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | POST | ID of Organisation | N/A | YES |
| id | uint64 | POST | Organisation ID | N/A | YES |
## Update organisation details
@@ -16,8 +16,8 @@ Organisations represent a top-level grouping entity. There may be many organisat
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | POST | ID of Organisation | N/A | NO |
| name | string | POST | Name of Organisation | N/A | YES |
| id | uint64 | POST | Organisation ID | N/A | NO |
| name | string | POST | Organisation Name | N/A | YES |
## Read organisation details
@@ -25,7 +25,7 @@ Organisations represent a top-level grouping entity. There may be many organisat
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | GET | ID of Organisation | N/A | YES |
| id | uint64 | GET | Organisation ID | N/A | YES |
## Remove organisation
@@ -33,7 +33,7 @@ Organisations represent a top-level grouping entity. There may be many organisat
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | GET | ID of Organisation | N/A | YES |
| id | uint64 | GET | Organisation ID | N/A | YES |
## Search organisations
@@ -43,6 +43,9 @@ Organisations represent a top-level grouping entity. There may be many organisat
| --------- | ---- | ------ | ----------- | ------- | --------- |
| query | string | GET | Search query | N/A | NO |
# Teams
An organisation may have many teams. Teams may have many channels available. Access to channels may be shared between teams.
@@ -53,7 +56,7 @@ An organisation may have many teams. Teams may have many channels available. Acc
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | POST | ID of Organisation | N/A | YES |
| id | uint64 | POST | Organisation ID | N/A | YES |
## Update team details
@@ -61,7 +64,7 @@ An organisation may have many teams. Teams may have many channels available. Acc
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | POST | ID of Team | N/A | NO |
| id | uint64 | POST | Team ID | N/A | NO |
| name | string | POST | Name of Team | N/A | YES |
| members | []uint64 | POST | Team member IDs | N/A | NO |
@@ -71,8 +74,8 @@ An organisation may have many teams. Teams may have many channels available. Acc
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | POST | ID of Organisation | N/A | YES |
| organisation_id | uint64 | POST | ID of Organisation | N/A | YES |
| id | uint64 | POST | Organisation ID | N/A | YES |
| organisation_id | uint64 | POST | Organisation ID | N/A | YES |
## Read team details and memberships
@@ -80,7 +83,7 @@ An organisation may have many teams. Teams may have many channels available. Acc
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | GET | ID of Organisation | N/A | YES |
| id | uint64 | GET | Organisation ID | N/A | YES |
## Remove team
@@ -88,7 +91,7 @@ An organisation may have many teams. Teams may have many channels available. Acc
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | GET | ID of Organisation | N/A | YES |
| id | uint64 | GET | Organisation ID | N/A | YES |
## Search teams
@@ -98,6 +101,9 @@ An organisation may have many teams. Teams may have many channels available. Acc
| --------- | ---- | ------ | ----------- | ------- | --------- |
| query | string | GET | Search query | N/A | NO |
# Channels
A channel is a representation of a sequence of messages. It has meta data like channel subject. Channels may be public, private or direct (between two users).
@@ -108,7 +114,7 @@ A channel is a representation of a sequence of messages. It has meta data like c
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | POST | ID of Channel | N/A | YES |
| id | uint64 | POST | Channel ID | N/A | YES |
## Update channel details
@@ -116,7 +122,7 @@ A channel is a representation of a sequence of messages. It has meta data like c
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | POST | ID of Channel | N/A | NO |
| id | uint64 | POST | Channel ID | N/A | NO |
| name | string | POST | Name of Channel | N/A | YES |
| topic | string | POST | Subject of Channel | N/A | YES |
@@ -135,7 +141,7 @@ A channel is a representation of a sequence of messages. It has meta data like c
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | POST | ID of Channel | N/A | YES |
| id | uint64 | POST | Channel ID | N/A | YES |
## Read channel details
@@ -143,7 +149,7 @@ A channel is a representation of a sequence of messages. It has meta data like c
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | GET | ID of Channel | N/A | YES |
| id | uint64 | GET | Channel ID | N/A | YES |
## Remove channel
@@ -151,7 +157,7 @@ A channel is a representation of a sequence of messages. It has meta data like c
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | GET | ID of Channel | N/A | YES |
| id | uint64 | GET | Channel ID | N/A | YES |
## Search channels
@@ -161,6 +167,9 @@ A channel is a representation of a sequence of messages. It has meta data like c
| --------- | ---- | ------ | ----------- | ------- | --------- |
| query | string | GET | Search query | N/A | NO |
# Messages
Messages represent individual messages in the chat system. Messages are typed, indicating the event which triggered the message.
@@ -183,14 +192,21 @@ The following event types may be sent with a message event:
| EDITED | A message has been edited by the sender |
| REMOVED | A message has been removed by the sender |
## Attach file to message
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
## New message / edit message
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | POST | ID of Message | N/A | NO |
| channel_id | uint64 | POST | ID of Channel where to post message | N/A | NO |
| id | uint64 | POST | Message ID | N/A | NO |
| channel_id | uint64 | POST | Channel ID where to post message | N/A | NO |
| contents | string | POST | Message contents (markdown) | N/A | YES |
## Flag message for user (bookmark)
@@ -199,7 +215,7 @@ The following event types may be sent with a message event:
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | POST | ID of Message | N/A | YES |
| id | uint64 | POST | Message ID | N/A | YES |
## Pin message to channel (public bookmark)
@@ -207,7 +223,7 @@ The following event types may be sent with a message event:
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | POST | ID of Message | N/A | YES |
| id | uint64 | POST | Message ID | N/A | YES |
## Read message details
@@ -215,7 +231,7 @@ The following event types may be sent with a message event:
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| channel_id | uint64 | POST | ID of Channel to read messages from | N/A | YES |
| channel_id | uint64 | POST | Channel ID to read messages from | N/A | YES |
## Remove message
@@ -223,7 +239,7 @@ The following event types may be sent with a message event:
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | GET | ID of Message | N/A | YES |
| id | uint64 | GET | Message ID | N/A | YES |
## Search messages
@@ -234,6 +250,9 @@ The following event types may be sent with a message event:
| query | string | GET | Search string to match against messages | N/A | NO |
| message_type | string | GET | Limit results to message type | N/A<br><br>Values:<br><br><ul><li>`history`</li><li>`message`</li><li>`attachment`</li><li>`media`</li> | NO |
# Members
## Search members (Directory)
@@ -242,35 +261,4 @@ The following event types may be sent with a message event:
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
# Files
The Files API is an abstraction over messages that have been sent with a file attachment.
## Add new file
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
## Read file
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
## Remove file
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
## Search files
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| query | string | GET | Search query to match against users | N/A | NO |
docs/README.php
+8 -9
View File
@@ -29,23 +29,22 @@ function cleanUp($contents) {
}
$contents = implode("\n", $lines);
$contents = str_replace("`\n|", "` |", $contents);
return $contents;
$contents = preg_replace("/^# /sm", "\n\n\n# ", $contents);
return trim($contents);
}
$spec = json_decode(file_get_contents("src/_spec.json"), true);
$spec = json_decode(file_get_contents("src/spec.json"), true);
$apis = array();
foreach ($spec as $api) {
$entrypoint = $api['entrypoint'];
$filename = "src/" . $entrypoint . ".json";
$filenames_md = array("src/" . $entrypoint . ".md", "src/" . $entrypoint . "/index.md");
var_dump($entrypoint);
$filename = "src/spec/" . $entrypoint . ".json";
$filename_md = "src/" . $entrypoint . "/index.md";
$api = json_decode(file_get_contents($filename), true);
$api = array_change_key_case_recursive($api);
foreach ($filenames_md as $filename_md) {
if (file_exists($filename_md)) {
$api['description'] = file_get_contents($filename_md);
break;
}
if (file_exists($filename_md)) {
$api['description'] = file_get_contents($filename_md);
}
foreach ($api['apis'] as $name => $call) {
$filename_md = "src/" . $entrypoint . "/" . $name . ".md";
docs/src/file.json
-33
View File
@@ -1,33 +0,0 @@
{
"Title": "Files",
"Description": "The Files API is an abstraction over messages that have been sent with a file attachment.",
"Package": "crust",
"Interface": "File",
"Path": "/file",
"APIs": {
"add": {
"Method": "POST",
"Title": "Add new file",
"Path": "/add",
"Parameters": {}
},
"read": {
"Method": "GET",
"Title": "Read file",
"Path": "/read",
"Parameters": {}
},
"remove": {
"Method": "DELETE",
"Title": "Remove file",
"Path": "/remove",
"Parameters": {}
},
"search": {
"Method": "GET",
"Title": "Search files",
"Path": "/search",
"Parameters": {}
}
}
}
docs/src/member.json
-14
View File
@@ -1,14 +0,0 @@
{
"Title": "Members",
"Package": "crust",
"Interface": "Member",
"Path": "/member",
"APIs": {
"search": {
"Method": "GET",
"Title": "Search members (Directory)",
"Path": "/search",
"Parameters": {}
}
}
}
docs/src/message.md → docs/src/message/index.md
View File
docs/src/_spec.json → docs/src/spec.json
+38 -47
View File
@@ -10,8 +10,8 @@
"title": "Update organisation details",
"parameters": {
"post": [
{ "type": "uint64", "name": "id", "required": false, "title": "ID of Organisation" },
{ "type": "string", "name": "name", "required": true, "title": "Name of Organisation" }
{ "type": "uint64", "name": "id", "required": false, "title": "Organisation ID" },
{ "type": "string", "name": "name", "required": true, "title": "Organisation Name" }
]
}
},
@@ -20,7 +20,7 @@
"title": "Remove organisation",
"parameters": {
"get": [
{ "type": "uint64", "name": "id", "required": true, "title": "ID of Organisation" }
{ "type": "uint64", "name": "id", "required": true, "title": "Organisation ID" }
]
}
},
@@ -29,7 +29,7 @@
"title": "Read organisation details",
"parameters": {
"get": [
{ "type": "uint64", "name": "id", "required": true, "title": "ID of Organisation" }
{ "type": "uint64", "name": "id", "required": true, "title": "Organisation ID" }
]
}
},
@@ -47,7 +47,7 @@
"title": "Archive organisation",
"parameters": {
"post": [
{ "type": "uint64", "name": "id", "required": true, "title": "ID of Organisation" }
{ "type": "uint64", "name": "id", "required": true, "title": "Organisation ID" }
]
}
}
@@ -64,7 +64,7 @@
"title": "Update team details",
"parameters": {
"post": [
{ "type": "uint64", "name": "id", "required": false, "title": "ID of Team" },
{ "type": "uint64", "name": "id", "required": false, "title": "Team ID" },
{ "type": "string", "name": "name", "required": true, "title": "Name of Team" },
{ "type": "[]uint64", "name": "members", "required": false, "title": "Team member IDs" }
]
@@ -75,7 +75,7 @@
"title": "Remove team",
"parameters": {
"get": [
{ "type": "uint64", "name": "id", "required": true, "title": "ID of Organisation" }
{ "type": "uint64", "name": "id", "required": true, "title": "Organisation ID" }
]
}
},
@@ -84,7 +84,7 @@
"title": "Read team details and memberships",
"parameters": {
"get": [
{ "type": "uint64", "name": "id", "required": true, "title": "ID of Organisation" }
{ "type": "uint64", "name": "id", "required": true, "title": "Organisation ID" }
]
}
},
@@ -102,7 +102,7 @@
"title": "Archive team",
"parameters": {
"post": [
{ "type": "uint64", "name": "id", "required": true, "title": "ID of Organisation" }
{ "type": "uint64", "name": "id", "required": true, "title": "Organisation ID" }
]
}
},
@@ -111,8 +111,8 @@
"title": "Move team to different organisation",
"parameters": {
"POST": [
{ "type": "uint64", "name": "id", "required": true, "title": "ID of Organisation" },
{ "type": "uint64", "name": "organisation_id", "required": true, "title": "ID of Organisation" }
{ "type": "uint64", "name": "id", "required": true, "title": "Organisation ID" },
{ "type": "uint64", "name": "organisation_id", "required": true, "title": "Organisation ID" }
]
}
}
@@ -129,7 +129,7 @@
"title": "Update channel details",
"parameters": {
"post": [
{ "type": "uint64", "name": "id", "required": false, "title": "ID of Channel" },
{ "type": "uint64", "name": "id", "required": false, "title": "Channel ID" },
{ "type": "string", "name": "name", "required": true, "title": "Name of Channel" },
{ "type": "string", "name": "topic", "required": true, "title": "Subject of Channel" }
]
@@ -140,7 +140,7 @@
"title": "Remove channel",
"parameters": {
"get": [
{ "type": "uint64", "name": "id", "required": true, "title": "ID of Channel" }
{ "type": "uint64", "name": "id", "required": true, "title": "Channel ID" }
]
}
},
@@ -149,7 +149,7 @@
"title": "Read channel details",
"parameters": {
"get": [
{ "type": "uint64", "name": "id", "required": true, "title": "ID of Channel" }
{ "type": "uint64", "name": "id", "required": true, "title": "Channel ID" }
]
}
},
@@ -167,7 +167,7 @@
"title": "Archive channel",
"parameters": {
"post": [
{ "type": "uint64", "name": "id", "required": true, "title": "ID of Channel" }
{ "type": "uint64", "name": "id", "required": true, "title": "Channel ID" }
]
}
},
@@ -176,7 +176,7 @@
"title": "Move channel to different team or organisation",
"parameters": {
"post": [
{ "type": "uint64", "name": "id", "required": true, "title": "ID of Channel" }
{ "type": "uint64", "name": "id", "required": true, "title": "Channel ID" }
]
}
},
@@ -202,18 +202,28 @@
"title": "New message / edit message",
"parameters": {
"post": [
{ "type": "uint64", "name": "id", "required": false, "title": "ID of Message" },
{ "type": "uint64", "name": "channel_id", "required": false, "title": "ID of Channel where to post message" },
{ "type": "uint64", "name": "id", "required": false, "title": "Message ID" },
{ "type": "uint64", "name": "channel_id", "required": false, "title": "Channel ID where to post message" },
{ "type": "string", "name": "contents", "required": true, "title": "Message contents (markdown)" }
]
}
},
"attach": {
"method": "PUT",
"title": "Attach file to message",
"params": {
"get": [
{ "name": "message_id", "type": "uint64", "title": "Message ID" },
{ "name": "name", "type": "string", "title": "File name to drop" }
]
}
},
"remove": {
"method": "DELETE",
"title": "Remove message",
"parameters": {
"get": [
{ "type": "uint64", "name": "id", "required": true, "title": "ID of Message" }
{ "type": "uint64", "name": "id", "required": true, "title": "Message ID" }
]
}
},
@@ -222,7 +232,7 @@
"title": "Read message details",
"parameters": {
"post": [
{ "type": "uint64", "name": "channel_id", "required": true, "title": "ID of Channel to read messages from" }
{ "type": "uint64", "name": "channel_id", "required": true, "title": "Channel ID to read messages from" }
]
}
},
@@ -247,7 +257,7 @@
"title": "Pin message to channel (public bookmark)",
"parameters": {
"post": [
{ "type": "uint64", "name": "id", "required": true, "title": "ID of Message" }
{ "type": "uint64", "name": "id", "required": true, "title": "Message ID" }
]
}
},
@@ -256,7 +266,7 @@
"title": "Flag message for user (bookmark)",
"parameters": {
"post": [
{ "type": "uint64", "name": "id", "required": true, "title": "ID of Message" }
{ "type": "uint64", "name": "id", "required": true, "title": "Message ID" }
]
}
}
@@ -269,31 +279,12 @@
"apis": {
"search": {
"method": "GET",
"title": "Search members (Directory)"
}
}
},
{
"title": "Files",
"description": "The Files API is an abstraction over messages that have been sent with a file attachment.",
"package": "crust",
"entrypoint": "file",
"apis": {
"add": {
"method": "POST",
"title": "Add new file"
},
"read": {
"method": "GET",
"title": "Read file"
},
"remove": {
"method": "DELETE",
"title": "Remove file"
},
"search": {
"method": "GET",
"title": "Search files"
"title": "Search members (Directory)",
"parameters": {
"get": [
{ "type": "string", "name": "query", "required": false, "title": "Search query to match against users" }
]
}
}
}
}
docs/src/channel.json → docs/src/spec/channel.json
+5 -5
View File
@@ -14,7 +14,7 @@
{
"name": "id",
"required": true,
"title": "ID of Channel",
"title": "Channel ID",
"type": "uint64"
}
]
@@ -29,7 +29,7 @@
{
"name": "id",
"required": false,
"title": "ID of Channel",
"title": "Channel ID",
"type": "uint64"
},
{
@@ -77,7 +77,7 @@
{
"name": "id",
"required": true,
"title": "ID of Channel",
"title": "Channel ID",
"type": "uint64"
}
]
@@ -92,7 +92,7 @@
{
"name": "id",
"required": true,
"title": "ID of Channel",
"title": "Channel ID",
"type": "uint64"
}
]
@@ -107,7 +107,7 @@
{
"name": "id",
"required": true,
"title": "ID of Channel",
"title": "Channel ID",
"type": "uint64"
}
]
docs/src/spec/member.json
+23
View File
@@ -0,0 +1,23 @@
{
"Title": "Members",
"Package": "crust",
"Interface": "Member",
"Path": "/member",
"APIs": {
"search": {
"Method": "GET",
"Title": "Search members (Directory)",
"Path": "/search",
"Parameters": {
"get": [
{
"name": "query",
"required": false,
"title": "Search query to match against users",
"type": "string"
}
]
}
}
}
}
docs/src/message.json → docs/src/spec/message.json
+12 -6
View File
@@ -4,6 +4,12 @@
"Interface": "Message",
"Path": "/message",
"APIs": {
"attach": {
"Method": "PUT",
"Title": "Attach file to message",
"Path": "/attach",
"Parameters": null
},
"edit": {
"Method": "POST",
"Title": "New message / edit message",
@@ -13,13 +19,13 @@
{
"name": "id",
"required": false,
"title": "ID of Message",
"title": "Message ID",
"type": "uint64"
},
{
"name": "channel_id",
"required": false,
"title": "ID of Channel where to post message",
"title": "Channel ID where to post message",
"type": "uint64"
},
{
@@ -40,7 +46,7 @@
{
"name": "id",
"required": true,
"title": "ID of Message",
"title": "Message ID",
"type": "uint64"
}
]
@@ -55,7 +61,7 @@
{
"name": "id",
"required": true,
"title": "ID of Message",
"title": "Message ID",
"type": "uint64"
}
]
@@ -70,7 +76,7 @@
{
"name": "channel_id",
"required": true,
"title": "ID of Channel to read messages from",
"title": "Channel ID to read messages from",
"type": "uint64"
}
]
@@ -85,7 +91,7 @@
{
"name": "id",
"required": true,
"title": "ID of Message",
"title": "Message ID",
"type": "uint64"
}
]
docs/src/organisation.json → docs/src/spec/organisation.json
+5 -5
View File
@@ -14,7 +14,7 @@
{
"name": "id",
"required": true,
"title": "ID of Organisation",
"title": "Organisation ID",
"type": "uint64"
}
]
@@ -29,13 +29,13 @@
{
"name": "id",
"required": false,
"title": "ID of Organisation",
"title": "Organisation ID",
"type": "uint64"
},
{
"name": "name",
"required": true,
"title": "Name of Organisation",
"title": "Organisation Name",
"type": "string"
}
]
@@ -50,7 +50,7 @@
{
"name": "id",
"required": true,
"title": "ID of Organisation",
"title": "Organisation ID",
"type": "uint64"
}
]
@@ -65,7 +65,7 @@
{
"name": "id",
"required": true,
"title": "ID of Organisation",
"title": "Organisation ID",
"type": "uint64"
}
]
docs/src/team.json → docs/src/spec/team.json
+6 -6
View File
@@ -14,7 +14,7 @@
{
"name": "id",
"required": true,
"title": "ID of Organisation",
"title": "Organisation ID",
"type": "uint64"
}
]
@@ -29,7 +29,7 @@
{
"name": "id",
"required": false,
"title": "ID of Team",
"title": "Team ID",
"type": "uint64"
},
{
@@ -56,13 +56,13 @@
{
"name": "id",
"required": true,
"title": "ID of Organisation",
"title": "Organisation ID",
"type": "uint64"
},
{
"name": "organisation_id",
"required": true,
"title": "ID of Organisation",
"title": "Organisation ID",
"type": "uint64"
}
]
@@ -77,7 +77,7 @@
{
"name": "id",
"required": true,
"title": "ID of Organisation",
"title": "Organisation ID",
"type": "uint64"
}
]
@@ -92,7 +92,7 @@
{
"name": "id",
"required": true,
"title": "ID of Organisation",
"title": "Organisation ID",
"type": "uint64"
}
]