From f676dba15944a45c4bd846f772487ff5feb9e537 Mon Sep 17 00:00:00 2001 From: Tyler Renelle Date: Wed, 1 Jan 2014 16:23:06 -0700 Subject: [PATCH] #2217 more progress documenting API --- src/apidoc.coffee | 141 +++++++++++++++++++++++++++++++++++++++------- 1 file changed, 122 insertions(+), 19 deletions(-) diff --git a/src/apidoc.coffee b/src/apidoc.coffee index 430712519d..4eb05a5d26 100644 --- a/src/apidoc.coffee +++ b/src/apidoc.coffee @@ -1,8 +1,10 @@ # see https://github.com/wordnik/swagger-node-express _ = require('lodash') +content = require('habitrpg-shared').content module.exports = (swagger) -> + [path,body,query] = [swagger.pathParam, swagger.bodyParam, swagger.queryParam] swagger.configureSwaggerPaths("", "/api-docs", "") @@ -24,8 +26,8 @@ module.exports = (swagger) -> "/user/tasks/{id}/{direction}": description: "Simple scoring of a task" params: [ - swagger.pathParam("id", "ID of the task to score. If this task doesn't exist, a task will be created automatically", "string") - swagger.pathParam("direction", "Either 'up' or 'down'", "string") + path("id", "ID of the task to score. If this task doesn't exist, a task will be created automatically", "string") + path("direction", "Either 'up' or 'down'", "string") ] method: 'POST' @@ -36,92 +38,194 @@ module.exports = (swagger) -> "/user/tasks/{id}": description: "Get an individual task" params: [ - swagger.pathParam("id", "Task ID", "string") + path("id", "Task ID", "string") ] "/user/tasks/{id}": description: "Update a user's task" method: 'PUT' params: [ - swagger.pathParam("id", "Task ID", "string") - ] - body: [ - swagger.bodyParam("task","Send up the whole task","string") + path("id", "Task ID", "string") + body("","Send up the whole task","object") ] "/user/tasks/{id}": + description: "Delete a task" method: 'DELETE' + params: [ path("id", "Task ID", "string") ] + "/user/tasks": + description: "Create a task" method: 'POST' - #body={} + params: [ body("","Send up the whole task","object") ] + "/user/tasks/{id}/sort": method: 'POST' - #query={to,from} + description: 'Sort tasks' + params: [ + path("id", "Task ID", "string") + query("from","Index where you're sorting from (0-based)","integer") + query("to","Index where you're sorting to (0-based)","integer") + ] + "/user/tasks/clear-completed": method: 'POST' + description: "Clears competed To-Dos (needed periodically for performance." + "/user/tasks/{id}/unlink": method: 'POST' + description: 'Unlink a task from its challenge' + # TODO query params? + params: [path("id", "Task ID", "string")] + # Inventory "/user/inventory/buy/{key}": method: 'POST' + description: "Buy a gear piece and equip it automatically" + params:[ + path 'key',"The key of the item to buy (call /content route for available keys)",'string', _.keys(content.gear.flat) + #TODO embed keys + ] + "/user/inventory/sell/{type}/{key}": method: 'POST' + description: "Sell inventory items back to Alexander" + params: [ + #TODO verify these are the correct types + path('type',"The type of object you're selling back.",'string',['gear','eggs','hatchingPotions','food']) + path('key',"The object key you're selling back (call /content route for available keys)",'string') + ] + "/user/inventory/purchase/{type}/{key}": method: 'POST' + description: "Purchase a gem-purchaseable item from Alexander" + params:[ + path('type',"The type of object you're purchasing.",'string',['gear','eggs','hatchingPotions','food']) + path('key',"The object key you're purchasing (call /content route for available keys)",'string') + ] + "/user/inventory/feed/{pet}/{food}": method: 'POST' + description: "Feed your pet some food" + params: [ + path 'pet',"The key of the pet you're feeding",'string'#,_.keys(content.pets)) + path 'food',"The key of the food to feed your pet",'string',_.keys(content.food) + ] + "/user/inventory/equip/{type}/{key}": method: 'POST' + description: "Equip an item (either pets, mounts, or gear)" + params: [ + path 'type',"Type to equip",'string',['pets','mounts','gear'] + path 'key',"The object key you're equipping (call /content route for available keys)",'string' + ] + "/user/inventory/hatch/{egg}/{hatchingPotion}": method: 'POST' + description: "Pour a hatching potion on an egg" + params: [ + path 'egg',"The egg key to hatch",'string',_.keys(content.eggs) + path 'hatchingPotion',"The hatching potion to pour",'string',_.keys(content.hatchingPotions) + ] # User "/user:GET": path: '/user' + description: "Get the full user object" + "/user:PUT": path: '/user' method: 'PUT' - # body={} + description: "Update the user object (only certain attributes are supported)" + params: [ + body '','The user object','object' + ] + "/user:DELETE": path: '/user' method: 'DELETE' + description: "Delete a user object entirely, USE WITH CAUTION!" + "/user/revive": method: 'POST' + description: "Revive your dead user" + "/user/reroll": method: 'POST' + description: 'Drink the Fortify Potion (Note, it used to be called re-roll)' + "/user/reset": method: 'POST' + description: "Completely reset your account" + "/user/sleep": method: 'POST' + description: "Toggle whether you're resting in the inn" + "/user/rebirth": method: 'POST' + description: "Rebirth your avatar" + "/user/class/change": method: 'POST' - #query={class} + description: "Either remove your avatar's class, or change it to something new" + params: [ + query 'class',"The key of the class to change to. If not provided, user's class is removed.",'string',['warrior','healer','rogue','wizard',''] + ] + "/user/class/allocate": method: 'POST' - #query={stat} - "/user/class/cast/:spell": + description: "Allocate one point towards an attribute" + params: [ + query 'stat','The stat to allocate towards','string' + ] + + "/user/class/cast/{spell}": method: 'POST' + description: "Cast a spell" + #TODO finish + "/user/unlock": method: 'POST' - "/user/buy-gems": - method: 'POST' + description: "Unlock a certain gem-purchaseable path (or multiple paths)" + params: [ + query 'path',"The path to unlock, such as hair.green or shirts.red,shirts.blue",'string' + ] + "/user/batch-update": method: 'POST' + description: "This is an advanced route which is useful for apps which might for example need offline support. You can send a whole batch of user-based operations, which allows you to queue them up offline and send them all at once. The format is {op:'nameOfOperation',params:{},body:{},query:{}}" + params:[ + body '','The array of batch-operations to perform','object' + ] # Tags "/user/tags": method: 'POST' - #body={} + description: 'Create a new tag' + params: [ + #TODO document + body '','New tag','object' + ] + "/user/tags/{id}:PUT": path: 'user/tags/{id}' method: 'PUT' - #body={} + description: "Edit a tag" + params: [ + path 'id','The id of the tag to edit','string' + body '','Tag edits','object' + ] + "/user/tags/{id}:DELETE": path: 'user/tags/{id}' method: 'DELETE' + description: 'Delete a tag' + params: [ + path 'id','Id of tag to delete','string' + ] + # --------------------------------- # Groups @@ -203,7 +307,7 @@ module.exports = (swagger) -> # notes: "Returns a pet based on ID" # summary: "Find pet by ID" # method: "GET" - # params: [swagger.pathParam("petId", "ID of pet that needs to be fetched", "string")] + # params: [path("petId", "ID of pet that needs to be fetched", "string")] # type: "Pet" # errorResponses: [swagger.errors.invalid("id"), swagger.errors.notFound("pet")] # nickname: "getPetById" @@ -219,7 +323,6 @@ module.exports = (swagger) -> errorResponses: [] method: 'GET' route = {spec} - console.log(spec.params) swagger["add#{route.spec.method}"](route);true swagger.configure("http://localhost:3000", "0.1") \ No newline at end of file