Switch the Python side to Swagger v2

endpoints/api/billing.py

@@ -1,3 +1,5 @@
+""" Billing information, subscriptions, and plan information. """
+
 import stripe
 
 from flask import request
@@ -352,7 +354,7 @@ class UserInvoiceList(ApiResource):
 @path_param('orgname', 'The name of the organization')
 @related_user_resource(UserInvoiceList)
 @show_if(features.BILLING)
-class OrgnaizationInvoiceList(ApiResource):
+class OrganizationInvoiceList(ApiResource):
   """ Resource for listing an orgnaization's invoices. """
   @require_scope(scopes.ORG_ADMIN)
   @nickname('listOrgInvoices')

endpoints/api/build.py

@@ -1,3 +1,5 @@
+""" Create, list, cancel and get status/logs of repository builds. """
+
 import logging
 import json
 import time
@@ -165,7 +167,8 @@ class RepositoryBuildList(RepositoryParamResource):
         },
         'docker_tags': {
           'type': 'array',
-          'description': 'The tags to which the built images will be pushed',
+          'description': 'The tags to which the built images will be pushed. ' +
+                         'If none specified, "latest" is used.',
           'items': {
             'type': 'string'
           },

endpoints/api/discovery.py

@@ -1,5 +1,8 @@
+""" API discovery information. """
+
 import re
 import logging
+import sys
 
 from flask.ext.restful import reqparse
 
@@ -7,7 +10,7 @@ from endpoints.api import (ApiResource, resource, method_metadata, nickname, tru
                            parse_args, query_param)
 from app import app
 from auth import scopes
-
+from collections import OrderedDict
 
 logger = logging.getLogger(__name__)
 
@@ -32,162 +35,195 @@ def fully_qualified_name(method_view_class):
 
 
 def swagger_route_data(include_internal=False, compact=False):
-  apis = []
-  models = {}
-  for rule in app.url_map.iter_rules():
-    endpoint_method = app.view_functions[rule.endpoint]
 
-    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']))
-      for method_name in method_names:
-        method = getattr(view_class, method_name.lower(), None)
-
-        parameters = []
-
-        for param in rule.arguments:
-          parameters.append({
-            'paramType': 'path',
-            'name': param,
-            'dataType': 'string',
-            'description': param_data_map.get(param, {'description': ''})['description'],
-            'required': True,
-          })
-
-        if method is None:
-          logger.debug('Unable to find method for %s in class %s', method_name, view_class)
-        else:
-          req_schema_name = method_metadata(method, 'request_schema')
-          if req_schema_name:
-            parameters.append({
-              'paramType': 'body',
-              'name': 'body',
-              'description': 'Request body contents.',
-              'dataType': req_schema_name,
-              'required': True,
-            })
-
-            schema = view_class.schemas[req_schema_name]
-            models[req_schema_name] = schema
-
-          if '__api_query_params' in dir(method):
-            for param_spec in method.__api_query_params:
-              new_param = {
-                'paramType': 'query',
-                'name': param_spec['name'],
-                'description': param_spec['help'],
-                'dataType': TYPE_CONVERTER[param_spec['type']],
-                'required': param_spec['required'],
-              }
-
-              if len(param_spec['choices']) > 0:
-                new_param['enum'] = list(param_spec['choices'])
-
-              parameters.append(new_param)
-
-          new_operation = {
-            'method': method_name,
-            'nickname': method_metadata(method, 'nickname') or '(unnamed)'
+  def swagger_parameter(name, description, kind='path', param_type='string', required=True,
+                        enum=None, schema=None):
+    # https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#parameterObject
+    parameter_info = {
+      'name': name,
+      'in': kind,
+      'required': required
     }
 
     if not compact:
-            response_type = 'void'
-            res_schema_name = method_metadata(method, 'response_schema')
-            if res_schema_name:
-              models[res_schema_name] = view_class.schemas[res_schema_name]
-              response_type = res_schema_name
+      parameter_info['description'] = description or ''
 
-            new_operation.update({
-              'type': response_type,
-              'summary': method.__doc__.strip() if method.__doc__ else '',
-              'parameters': parameters,
+    if schema:
+      parameter_info['schema'] = {
+        '$ref': '#/definitions/%s' % schema
+      }
+    else:
+      parameter_info['type'] = param_type
+
+    if enum is not None and len(list(enum)) > 0:
+      parameter_info['enum'] = list(enum)
+
+    return parameter_info
+
+
+  paths = {}
+  models = {}
+  tags = []
+  tags_added = set()
+
+  for rule in app.url_map.iter_rules():
+    endpoint_method = app.view_functions[rule.endpoint]
+
+    # Verify that we have a view class for this API method.
+    if not 'view_class' in dir(endpoint_method):
+      continue
+
+    view_class = endpoint_method.view_class
+
+    # Hide the class if it is internal.
+    internal = method_metadata(view_class, 'internal')
+    if not include_internal and internal:
+      continue
+
+    # Build the tag.
+    parts = fully_qualified_name(view_class).split('.')
+    tag_name = parts[-2]
+    if not tag_name in tags_added:
+      tags_added.add(tag_name)
+      tags.append({
+        'name': tag_name,
+        'description': (sys.modules[view_class.__module__].__doc__ or '').strip()
       })
 
-
-          scope = method_metadata(method, 'oauth2_scope')
-          if scope and not compact:
-            new_operation['authorizations'] = {
-              'oauth2': [
-                {
-                  'scope': scope.scope
-                }
-              ],
+    # Build the Swagger data for the path.
+    swagger_path = PARAM_REGEX.sub(r'{\2}', rule.rule)
+    path_swagger = {
+      'name': fully_qualified_name(view_class),
+      'tag': tag_name
     }
 
+    paths[swagger_path] = path_swagger
+
+    # Add any global path parameters.
+    param_data_map = view_class.__api_path_params if '__api_path_params' in dir(view_class) else {}
+    if param_data_map:
+      path_parameters_swagger = []
+      for path_parameter in param_data_map:
+        description = param_data_map[path_parameter].get('description')
+        path_parameters_swagger.append(swagger_parameter(path_parameter, description))
+
+      path_swagger['parameters'] = path_parameters_swagger
+
+    # Add the individual HTTP operations.
+    method_names = list(rule.methods.difference(['HEAD', 'OPTIONS']))
+    for method_name in method_names:
+      # https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operation-object
+      method = getattr(view_class, method_name.lower(), None)
+      if method is None:
+        logger.debug('Unable to find method for %s in class %s', method_name, view_class)
+        continue
+
+      operation_swagger = {
+        'operationId': method_metadata(method, 'nickname') or 'unnamed',
+        'parameters': [],
+      }
+
+      if not compact:
+        operation_swagger.update({
+          'description': method.__doc__.strip() if method.__doc__ else '',
+          'tags': [tag_name]
+        })
+
+      # Mark the method as internal.
       internal = method_metadata(method, 'internal')
       if internal is not None:
-            new_operation['internal'] = True
+        operation_swagger['internal'] = True
 
       if include_internal:
         requires_fresh_login = method_metadata(method, 'requires_fresh_login')
         if requires_fresh_login is not None:
-              new_operation['requires_fresh_login'] = True
-
-          if not internal or (internal and include_internal):
-            # Swagger requires valid nicknames on all operations.
-            if new_operation.get('nickname'):
-              operations.append(new_operation)
-            else:
-              logger.debug('Operation missing nickname: %s' % method)
-
-      swagger_path = PARAM_REGEX.sub(r'{\2}', rule.rule)
-      new_resource = {
-        'path': swagger_path,
-        'description': view_class.__doc__.strip() if view_class.__doc__ else "",
-        'operations': operations,
-        'name': fully_qualified_name(view_class),
-      }
+          operation_swagger['requires_fresh_login'] = True
 
         related_user_res = method_metadata(view_class, 'related_user_resource')
         if related_user_res is not None:
-        new_resource['quayUserRelated'] = fully_qualified_name(related_user_res)
+          operation_swagger['quayUserRelated'] = fully_qualified_name(related_user_res)
 
-      internal = method_metadata(view_class, 'internal')
-      if internal is not None:
-        new_resource['internal'] = True
+      # Add the path parameters.
+      if rule.arguments:
+        for path_parameter in rule.arguments:
+          description = param_data_map.get(path_parameter, {}).get('description')
+          operation_swagger['parameters'].append(swagger_parameter(path_parameter, description))
 
+      # Add the query parameters.
+      if '__api_query_params' in dir(method):
+        for query_parameter_info in method.__api_query_params:
+          name = query_parameter_info['name']
+          description = query_parameter_info['help']
+          param_type = TYPE_CONVERTER[query_parameter_info['type']]
+          required = query_parameter_info['required']
+
+          operation_swagger['parameters'].append(
+            swagger_parameter(name, description, kind='query',
+                              param_type=param_type,
+                              required=required,
+                              enum=query_parameter_info['choices']))
+
+      # Add the OAuth security block.
+      # https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#securityRequirementObject
+      scope = method_metadata(method, 'oauth2_scope')
+      if scope and not compact:
+        operation_swagger['security'] = [{'oauth2_implicit': scope.scope}]
+
+      # TODO: Add the responses block.
+      # https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#responsesObject
+      response_schema_name = method_metadata(method, 'response_schema')
+      if response_schema_name and not compact:
+        models[response_schema_name] = view_class.schemas[response_schema_name]
+        response_type = response_schema_name
+
+      # Add the request block.
+      request_schema_name = method_metadata(method, 'request_schema')
+      if request_schema_name and not compact:
+        models[request_schema_name] = view_class.schemas[request_schema_name]
+
+        operation_swagger['parameters'].append(
+          swagger_parameter('body', 'Request body contents.', kind='body',
+                            schema=request_schema_name))
+
+      # Add the operation to the parent path.
       if not internal or (internal and include_internal):
-        apis.append(new_resource)
+        path_swagger[method_name.lower()] = operation_swagger
+
+  tags.sort(key=lambda t: t['name'])
+  paths = OrderedDict(sorted(paths.items(), key=lambda p: p[1]['tag']))
 
-  # If compact form was requested, simply return the APIs.
   if compact:
-    return {'apis': apis}
+    return {'paths': paths}
 
   swagger_data = {
-    'apiVersion': 'v1',
-    'swaggerVersion': '1.2',
-    'basePath': '%s://%s' % (PREFERRED_URL_SCHEME, SERVER_HOSTNAME),
-    'resourcePath': '/',
+    'swagger': '2.0',
+    'host': SERVER_HOSTNAME,
+    'basePath': '/',
+    'schemes': [
+      PREFERRED_URL_SCHEME
+    ],
     'info': {
-      'title': 'Quay.io API',
+      'version': 'v1',
+      'title': 'Quay.io Frontend',
       'description': ('This API allows you to perform many of the operations required to work '
                       'with Quay.io repositories, users, and organizations. You can find out more '
                       'at <a href="https://quay.io">Quay.io</a>.'),
-      'termsOfServiceUrl': 'https://quay.io/tos',
-      'contact': 'support@quay.io',
+      'termsOfService': 'https://quay.io/tos',
+      'contact': {
+        'email': 'support@quay.io'
+      }
     },
-    'authorizations': {
-      'oauth2': {
-        'scopes': [scope._asdict() for scope in scopes.ALL_SCOPES.values()],
-        'grantTypes': {
-          "implicit": {
-            "tokenName": "access_token",
-            "loginEndpoint": {
-              "url": "%s://%s/oauth/authorize" % (PREFERRED_URL_SCHEME, SERVER_HOSTNAME),
+    'securityDefinitions': {
+      'oauth2_implicit': {
+        "type": "oauth2",
+        "flow": "implicit",
+        "authorizationUrl": "%s://%s/oauth/authorize" % (PREFERRED_URL_SCHEME, SERVER_HOSTNAME),
+        'scopes': {scope.scope:scope.description for scope in scopes.ALL_SCOPES.values()},
       },
     },
-        },
-      },
-    },
-    'apis': apis,
-    'models': models,
+    'paths': paths,
+    'definitions': models,
+    'tags': tags
   }
 
   return swagger_data

endpoints/api/image.py

@@ -1,3 +1,5 @@
+""" List and lookup repository images, and download image diffs. """
+
 import json
 
 from collections import defaultdict

endpoints/api/logs.py

@@ -1,3 +1,5 @@
+""" Acces usage logs for organizations or repositories. """
+
 import json
 
 from datetime import datetime, timedelta

endpoints/api/organization.py

@@ -1,3 +1,5 @@
+""" Manage organizations, members and OAuth applications. """
+
 import logging
 
 from flask import request
@@ -333,7 +335,7 @@ def app_view(application):
 @resource('/v1/organization/<orgname>/applications')
 @path_param('orgname', 'The name of the organization')
 class OrganizationApplications(ApiResource):
-  """ Resource for managing applications defined by an organizations. """
+  """ Resource for managing applications defined by an organization. """
   schemas = {
     'NewApp': {
       'id': 'NewApp',

endpoints/api/permission.py

@@ -1,3 +1,5 @@
+""" Manage repository permissions. """
+
 import logging
 
 from flask import request

endpoints/api/prototype.py

@@ -1,3 +1,5 @@
+""" Manage default permissions added to repositories. """
+
 from flask import request
 
 from endpoints.api import (resource, nickname, ApiResource, validate_json_request, request_error,

endpoints/api/repoemail.py

@@ -1,3 +1,5 @@
+""" Authorize repository to send e-mail notifications. """
+
 import logging
 
 from flask import request, abort

endpoints/api/repository.py

@@ -1,3 +1,5 @@
+""" List, create and manage repositories. """
+
 import logging
 import json
 import datetime

endpoints/api/repositorynotification.py

@@ -1,3 +1,5 @@
+""" List, create and manage repository events/notifications. """
+
 import json
 
 from flask import request, abort

endpoints/api/repotoken.py

@@ -1,3 +1,5 @@
+""" Manage repository access tokens (DEPRECATED). """
+
 import logging
 
 from flask import request

endpoints/api/robot.py

@@ -1,3 +1,5 @@
+""" Manage user and organization robot accounts. """
+
 from endpoints.api import (resource, nickname, ApiResource, log_action, related_user_resource,
                            Unauthorized, require_user_admin, internal_only, require_scope,
                            path_param, parse_args, truthy_bool, query_param)
@@ -68,7 +70,6 @@ def robots_list(prefix, include_permissions=False):
   return {'robots': robots.values()}
 
 @resource('/v1/user/robots')
-@internal_only
 class UserRobotList(ApiResource):
   """ Resource for listing user robots. """
   @require_user_admin
@@ -85,7 +86,6 @@ 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. """
   @require_user_admin
@@ -181,7 +181,6 @@ class OrgRobot(ApiResource):
 
 @resource('/v1/user/robots/<robot_shortname>/permissions')
 @path_param('robot_shortname', 'The short name for the robot, without any user or organization prefix')
-@internal_only
 class UserRobotPermissions(ApiResource):
   """ Resource for listing the permissions a user's robot has in the system. """
   @require_user_admin
@@ -222,7 +221,6 @@ class OrgRobotPermissions(ApiResource):
 
 @resource('/v1/user/robots/<robot_shortname>/regenerate')
 @path_param('robot_shortname', 'The short name for the robot, without any user or organization prefix')
-@internal_only
 class RegenerateUserRobot(ApiResource):
   """ Resource for regenerate an organization's robot's token. """
   @require_user_admin

endpoints/api/search.py

@@ -1,3 +1,5 @@
+""" Conduct searches against all registry context. """
+
 from endpoints.api import (ApiResource, parse_args, query_param, truthy_bool, nickname, resource,
                            require_scope, path_param)
 from data import model

endpoints/api/subscribe.py

@@ -1,3 +1,5 @@
+""" Subscribe to plans. """
+
 import logging
 import stripe
 

endpoints/api/suconfig.py

@@ -1,3 +1,5 @@
+""" Superuser Config API. """
+
 import logging
 import os
 import json

endpoints/api/superuser.py

@@ -1,3 +1,5 @@
+""" Superuser API. """
+
 import string
 import logging
 import json

endpoints/api/tag.py

@@ -1,3 +1,5 @@
+""" Manage the tags of a repository. """
+
 from flask import request, abort
 
 from endpoints.api import (resource, nickname, require_repo_read, require_repo_write,

endpoints/api/team.py

@@ -1,3 +1,5 @@
+""" Create, list and manage an organization's teams. """
+
 from flask import request
 
 from endpoints.api import (resource, nickname, ApiResource, validate_json_request, request_error,

endpoints/api/trigger.py

@@ -1,3 +1,5 @@
+""" Create, list and manage build triggers. """
+
 import json
 import logging
 
@@ -397,7 +399,7 @@ class ActivateBuildTrigger(RepositoryParamResource):
       'properties': {
         'branch_name': {
           'type': 'string',
-          'description': '(GitHub Only) If specified, the name of the GitHub branch to build.'
+          'description': '(SCM only) If specified, the name of the branch to build.'
         },
         'commit_sha': {
           'type': 'string',

endpoints/api/user.py

@@ -1,3 +1,5 @@
+""" Manage the current user. """
+
 import logging
 import json
 
@@ -182,11 +184,17 @@ class User(ApiResource):
         },
         'organizations': {
           'type': 'array',
-          'description': 'Information about the organizations in which the user is a member'
+          'description': 'Information about the organizations in which the user is a member',
+          'items': {
+            'type': 'object'
+          }
         },
         'logins': {
           'type': 'array',
-          'description': 'The list of external login providers against which the user has authenticated'
+          'description': 'The list of external login providers against which the user has authenticated',
+          'items': {
+            'type': 'object'
+          }
         },
         'can_create_repo': {
           'type': 'boolean',
@@ -794,10 +802,10 @@ class StarredRepositoryList(ApiResource):
 @path_param('repository', 'The full path of the repository. e.g. namespace/name')
 class StarredRepository(RepositoryParamResource):
   """ Operations for managing a specific starred repository. """
-
   @nickname('deleteStar')
   @require_user_admin
   def delete(self, namespace, repository):
+    """ Removes a star from a repository. """
     user = get_authenticated_user()
     repo = model.get_repository(namespace, repository)