glenux-contrib/metamaps--metamaps
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

Merge pull request #714 from metamaps/feature/raml-1.0

Browse source 
update raml and create a build script for it
This commit is contained in:
Devin Howard 2016-10-04 16:10:02 +08:00 committed by GitHub
parent da3795a2c2 8afef1bc4a
commit c58a8da1a6
25 changed files with 190 additions and 60 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
.gitignore vendored
View file

@ -7,6 +7,7 @@
#assety stuff
public/assets
public/metamaps_mobile
public/api/index.html
vendor/
node_modules
npm-debug.log

3
app/controllers/api/v2/mappings_controller.rb
View file

@ -2,6 +2,9 @@
module Api
module V2
class MappingsController < RestfulController
def searchable_columns
[]
end
end
end
end

17
app/controllers/api/v2/tokens_controller.rb
View file

@ -2,6 +2,23 @@
module Api
module V2
class TokensController < RestfulController
def searchable_columns
[:description]
end
def create
if params[:token].blank?
self.resource = resource_class.new
else
instantiate_resource
end
resource.user = current_user if current_user.present?
authorize resource
create_action
respond_with_resource
end
def my_tokens
authorize resource_class
instantiate_collection

3
app/controllers/api/v2/topics_controller.rb
View file

@ -2,6 +2,9 @@
module Api
module V2
class TopicsController < RestfulController
def searchable_columns
[:name, :desc, :link]
end
end
end
end

5
bin/build-apidocs.sh Executable file
View file

@ -0,0 +1,5 @@
#!/bin/bash
# Note: you need to run `npm install` before using this script or raml2html won't be installed
./node_modules/.bin/raml2html -i ./doc/api/api.raml -o ./public/api/index.html

37
doc/api/api.raml
View file

@ -2,35 +2,30 @@
---
title: Metamaps
version: v2
baseUri: http://metamaps.cc/api/v2
baseUri: https://metamaps.cc/api/v2
mediaType: application/json
securitySchemes:
- oauth_2_0:
description: |
OAuth 2.0 implementation
type: OAuth 2.0
settings:
authorizationUri: https://metamaps.cc/api/v2/oauth/authorize
accessTokenUri: https://metamaps.cc/api/v2/oauth/token
authorizationGrants: [ authorization_code, password, client_credentials, implicit, refresh_token ]
oauth_2_0: !include securitySchemes/oauth_2_0.raml
securedBy: [ oauth_2_0 ]
traits:
- pageable: !include traits/pageable.raml
- orderable: !include traits/orderable.raml
- searchable: !include traits/searchable.raml
pageable: !include traits/pageable.raml
embeddable: !include traits/embeddable.raml
orderable: !include traits/orderable.raml
searchable: !include traits/searchable.raml
schemas:
- topic: !include schemas/_topic.json
- synapse: !include schemas/_synapse.json
- map: !include schemas/_map.json
- mapping: !include schemas/_mapping.json
- token: !include schemas/_token.json
topic: !include schemas/_topic.json
synapse: !include schemas/_synapse.json
map: !include schemas/_map.json
mapping: !include schemas/_mapping.json
token: !include schemas/_token.json
resourceTypes:
- base: !include resourceTypes/base.raml
- item: !include resourceTypes/item.raml
- collection: !include resourceTypes/collection.raml
#resourceTypes:
# base: !include resourceTypes/base.raml
# item: !include resourceTypes/item.raml
# collection: !include resourceTypes/collection.raml
/topics: !include apis/topics.raml
/synapses: !include apis/synapses.raml

31
doc/api/apis/mappings.raml
View file

@ -1,5 +1,6 @@
type: collection
#type: collection
get:
is: [ embeddable: { embedFields: "user,map" }, orderable, pageable ]
responses:
200:
body:
@ -16,17 +17,20 @@ post:
map_id:
description: id of the map
xloc:
description: (for Topic mappings only) x location on the canvas
description: (only for Topic mappings) x location on the canvas
required: false
yloc:
description: (for Topic mappings only) y location on the canvas
description: (only for Topic mappings) y location on the canvas
required: false
responses:
201:
body:
application/json:
example: !include ../examples/mapping.json
/{id}:
type: item
#type: item
get:
is: [ embeddable: { embedFields: "user,map" } ]
responses:
200:
body:
@ -38,10 +42,20 @@ post:
properties:
mappable_id:
description: id of the topic/synapse to be mapped
required: false
mappable_type:
description: Topic or Synapse
required: false
map_id:
description: id of the map
required: false
xloc:
description: (only for Topic mappings) x location on the canvas
required: false
yloc:
description: (only for Topic mappings) y location on the canvas
required: false
responses:
200:
body:
@ -53,10 +67,19 @@ post:
properties:
mappable_id:
description: id of the topic/synapse to be mapped
required: false
mappable_type:
description: Topic or Synapse
required: false
map_id:
description: id of the map
required: false
xloc:
description: (only for Topic mappings) x location on the canvas
required: false
yloc:
description: (only for Topic mappings) y location on the canvas
required: false
responses:
200:
body:

18
doc/api/apis/maps.raml
View file

@ -1,5 +1,6 @@
type: collection
#type: collection
get:
is: [ searchable: { searchFields: "name, desc" }, embeddable: { embedFields: "user,topics,synapses,mappings,contributors,collaborators" }, orderable, pageable ]
responses:
200:
body:
@ -27,8 +28,9 @@ post:
application/json:
example: !include ../examples/map.json
/{id}:
type: item
#type: item
get:
is: [ embeddable: { embedFields: "user,topics,synapses,mappings,contributors,collaborators" } ]
responses:
200:
body:
@ -40,16 +42,22 @@ post:
properties:
name:
description: name
required: false
desc:
description: description
required: false
permission:
description: commons, public, or private
required: false
screenshot:
description: url to a screenshot of the map
required: false
contributor_ids:
description: the topic being linked from
required: false
collaborator_ids:
description: the topic being linked to
required: false
responses:
200:
body:
@ -61,16 +69,22 @@ post:
properties:
name:
description: name
required: false
desc:
description: description
required: false
permission:
description: commons, public, or private
required: false
screenshot:
description: url to a screenshot of the map
required: false
contributor_ids:
description: the topic being linked from
required: false
collaborator_ids:
description: the topic being linked to
required: false
responses:
200:
body:

34
doc/api/apis/synapses.raml
View file

@ -1,5 +1,6 @@
type: collection
#type: collection
get:
is: [ searchable: { searchFields: "desc" }, embeddable: { embedFields: "topic1,topic2,user" }, orderable, pageable ]
responses:
200:
body:
@ -10,9 +11,11 @@ post:
application/json:
properties:
desc:
description: name
description: text description of this synapse
required: false
category:
description: from to or both
description: |
<code>from-to</code> or <code>both</code>
permission:
description: commons, public, or private
topic1_id:
@ -27,8 +30,9 @@ post:
application/json:
example: !include ../examples/synapse.json
/{id}:
type: item
#type: item
get:
is: [ embeddable: { embedFields: "topic1,topic2,user" } ]
responses:
200:
body:
@ -39,17 +43,24 @@ post:
application/json:
properties:
desc:
description: name
description: text description of this synapse
required: false
category:
description: from-to or both
description: |
<code>from-to</code> or <code>both</code>
required: false
permission:
description: commons, public, or private
required: false
topic1_id:
description: the topic being linked from
required: false
topic2_id:
description: the topic being linked to
required: false
user_id:
description: the creator of the topic
required: false
responses:
200:
body:
@ -60,17 +71,24 @@ post:
application/json:
properties:
desc:
description: name
description: text description of this synapse
required: false
category:
description: from-to or both
description: |
<code>from-to</code> or <code>both</code>
required: false
permission:
description: commons, public, or private
required: false
topic1_id:
description: the topic being linked from
required: false
topic2_id:
description: the topic being linked to
required: false
user_id:
description: the creator of the topic
required: false
responses:
200:
body:

6
doc/api/apis/tokens.raml
View file

@ -1,10 +1,11 @@
type: collection
#type: collection
post:
body:
application/json:
properties:
description:
description: short string describing this token
required: false
responses:
201:
body:
@ -12,13 +13,14 @@ post:
example: !include ../examples/token.json
/my_tokens:
get:
is: [ searchable: { searchFields: description }, pageable, orderable ]
responses:
200:
body:
application/json:
example: !include ../examples/tokens.json
/{id}:
type: item
#type: item
delete:
responses:
204:

39
doc/api/apis/topics.raml
View file

@ -1,5 +1,6 @@
type: collection
#type: collection
get:
is: [ searchable: { searchFields: "name, desc, link" }, embeddable: { embedFields: "user,metacode" }, orderable, pageable ]
responses:
200:
body:
@ -10,11 +11,12 @@ post:
application/json:
properties:
name:
description: name
description: Topic name; this will be visible on the map
desc:
description: description
description: Longer topic description visible when opening a map card
link:
description: (optional) link to content on the web
description: embed a link to content on the web in the topic card
required: false
permission:
description: commons, public, or private
metacode_id:
@ -25,8 +27,9 @@ post:
application/json:
example: !include ../examples/topic.json
/{id}:
type: item
#type: item
get:
is: [ embeddable: { embedFields: "user,metacode" } ]
responses:
200:
body:
@ -37,13 +40,20 @@ post:
application/json:
properties:
name:
description: name
description: Topic name; this will be visible on the map
required: false
desc:
description: description
description: Longer topic description visible when opening a map card
required: false
link:
description: (optional) link to content on the web
description: embed a link to content on the web in the topic card
required: false
permission:
description: commons, public, or private
required: false
metacode_id:
description: Topic's metacode
required: false
responses:
200:
body:
@ -54,13 +64,20 @@ post:
application/json:
properties:
name:
description: name
description: Topic name; this will be visible on the map
required: false
desc:
description: description
description: Longer topic description visible when opening a map card
required: false
link:
description: (optional) link to content on the web
description: embed a link to content on the web in the topic card
required: false
permission:
description: commons, public, or private
required: false
metacode_id:
description: Topic's metacode
required: false
responses:
200:
body:

6
doc/api/examples/topic.json
View file

@ -1,9 +1,9 @@
{
"data": {
"id": 670,
"name": "Junto feedback and enhancements map",
"desc": "",
"link": "",
"name": "Metamaps.cc Website",
"desc": "Metamaps is a great website; check it out below!",
"link": "https://metamaps.cc",
"permission": "commons",
"created_at": "2016-07-02T09:23:30.397Z",
"updated_at": "2016-07-02T09:23:30.397Z",

6
doc/api/examples/topics.json
View file

@ -2,9 +2,9 @@
"data": [
{
"id": 670,
"name": "Junto feedback and enhancements map",
"desc": "",
"link": "",
"name": "Metamaps.cc Website",
"desc": "Metamaps is a great website; check it out below!",
"link": "https://metamaps.cc",
"permission": "commons",
"created_at": "2016-07-02T09:23:30.397Z",
"updated_at": "2016-07-02T09:23:30.397Z",

2
doc/api/resourceTypes/collection.raml
View file

@ -16,7 +16,7 @@ get?:
post?:
description: Create a new <<resourcePathName | !singularize>>
responses:
200:
201:
body:
application/json:
schema: <<resourcePathName | !singularize>>

2
doc/api/resourceTypes/item.raml
View file

@ -1,3 +1,4 @@
type: base
get?:
description: Get a <<resourcePathName | !singularize>>
responses:
@ -26,4 +27,3 @@ delete?:
responses:
204:
description: Removed
type: base

1
doc/api/schemas/_page.json
View file

@ -35,4 +35,3 @@
"per"
]
}

1
doc/api/schemas/error.json Normal file
View file

@ -0,0 +1 @@
{}

7
doc/api/securitySchemes/oauth_2_0.raml Normal file
View file

@ -0,0 +1,7 @@
description: |
OAuth 2.0 implementation
type: OAuth 2.0
settings:
authorizationUri: https://metamaps.cc/api/v2/oauth/authorize
accessTokenUri: https://metamaps.cc/api/v2/oauth/token
authorizationGrants: [ authorization_code, client_credentials ]

8
doc/api/traits/embeddable.raml Normal file
View file

@ -0,0 +1,8 @@
queryParameters:
embed:
description: |
Comma-separated list of columns to embed. Each embedded column will be returned instead of the corresponding <code>field_id</code> or <code>field_ids</code> column. For instance, <code>?embed=user</code> would remove the <code>user_id</code> integer field from a response and replace it with a <code>user</code> object field.
Possible embeddable fields are: <pre><< embedFields >></pre>
required: false
type: string

4
doc/api/traits/orderable.raml
View file

@ -1,3 +1,5 @@
queryParameters:
sort:
description: The name of the field to sort by, prefixed by "-" to sort descending
description: The name of the comma-separated fields to sort by, prefixed by "-" to sort descending
required: false
type: string

4
doc/api/traits/pageable.raml
View file

@ -2,6 +2,10 @@ queryParameters:
page:
description: The page number
type: integer
required: false
default: 1
per:
description: Number of records per page
type: integer
required: false
default: 25

4
doc/api/traits/searchable.raml
View file

@ -1,4 +1,6 @@
queryParameters:
q:
description: The search string to query by
description: |
Search text columns for this string. A query of <code>"example"</code> will be passed to SQL as <code>LIKE %example%</code>. The searchable columns are: <pre><< searchFields >></pre>
required: false
type: string

9
doc/production/first-deploy.md
View file

@ -65,7 +65,14 @@ Run this in the metamaps directory, still as metamaps:
sudo aptitude install nodejs npm
sudo ln -s /usr/bin/nodejs /usr/bin/node
npm install
npm run build
#### Precompile assets
This step depends on running npm install first; assets:precompile will run `NODE_ENV=production npm run build`, and the build-apidocs.sh script requires the raml2html npm package.
rake assets:precompile
rake perms:fix
bin/build-apidocs.sh
#### Nginx and SSL

1
doc/production/pull-changes.md
View file

@ -26,6 +26,7 @@ Now that you have the code, run these commands:
npm install
rake db:migrate
rake assets:precompile # includes `npm run build`
bin/build-apidocs.sh
rake perms:fix
passenger-config restart-app .

1
package.json
View file

@ -31,6 +31,7 @@
"lodash": "4.16.1",
"node-uuid": "1.4.7",
"outdent": "0.2.1",
"raml2html": "^4.0.0-beta5",
"react": "15.3.2",
"react-dom": "15.3.2",
"socket.io": "0.9.12",