Add path param description support

endpoints/api/__init__.py

@@ -153,6 +153,18 @@ related_user_resource = partial(add_method_metadata, 'related_user_resource')
 internal_only = add_method_metadata('internal', True)
 
 
+def path_param(name, description):
+  def add_param(func):
+    if '__api_path_params' not in dir(func):
+      func.__api_path_params = {}
+    func.__api_path_params[name] = {
+      'name': name,
+      'description': description
+    }
+    return func
+  return add_param
+
+
 def query_param(name, help_str, type=reqparse.text_type, default=None,
                 choices=(), required=False):
   def add_param(func):

endpoints/api/discovery.py

@@ -39,6 +39,11 @@ def swagger_route_data(include_internal=False, compact=False):
 
     if 'view_class' in dir(endpoint_method):
       view_class = endpoint_method.view_class
+      
+      param_data_map = {}
+      if '__api_path_params' in dir(view_class):
+        param_data_map = view_class.__api_path_params
+
       operations = []
 
       method_names = list(rule.methods.difference(['HEAD', 'OPTIONS']))
@@ -46,12 +51,13 @@ def swagger_route_data(include_internal=False, compact=False):
         method = getattr(view_class, method_name.lower(), None)
 
         parameters = []
+
         for param in rule.arguments:
           parameters.append({
             'paramType': 'path',
             'name': param,
             'dataType': 'string',
-            'description': 'Param description.',
+            'description': param_data_map.get(param, {'description': ''})['description'],
             'required': True,
           })
 

endpoints/api/robot.py

@@ -1,5 +1,6 @@
 from endpoints.api import (resource, nickname, ApiResource, log_action, related_user_resource,
-                           Unauthorized, require_user_admin, internal_only, require_scope)
+                           Unauthorized, require_user_admin, internal_only, require_scope,
+                           path_param)
 from auth.permissions import AdministerOrganizationPermission, OrganizationMemberPermission
 from auth.auth_context import get_authenticated_user
 from auth import scopes
@@ -30,6 +31,7 @@ class UserRobotList(ApiResource):
 
 
 @resource('/v1/user/robots/<robot_shortname>')
+@path_param('robot_shortname', 'The short name for the robot, without any user or organization prefix')
 @internal_only
 class UserRobot(ApiResource):
   """ Resource for managing a user's robots. """
@@ -53,6 +55,7 @@ class UserRobot(ApiResource):
 
 
 @resource('/v1/organization/<orgname>/robots')
+@path_param('orgname', 'The name of the organization')
 @related_user_resource(UserRobotList)
 class OrgRobotList(ApiResource):
   """ Resource for listing an organization's robots. """
@@ -71,6 +74,8 @@ class OrgRobotList(ApiResource):
 
 
 @resource('/v1/organization/<orgname>/robots/<robot_shortname>')
+@path_param('orgname', 'The name of the organization')
+@path_param('robot_shortname', 'The short name for the robot, without any user or organization prefix')
 @related_user_resource(UserRobot)
 class OrgRobot(ApiResource):
   """ Resource for managing an organization's robots. """