Coverage for girder/api/v1/api_docs: 62%

# Coverage for girder/api/v1/api_docs : 62%

## 37 statements 23 run 14 missing 0 excluded

Hot-keys on this page

r m x p toggle line displays

j k next/prev highlighted chunk

0 (zero) top of page

1 (one) first highlighted chunk

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 | #!/usr/bin/env python # -*- coding: utf-8 -*- ############################################################################### # Copyright 2013 Kitware Inc. # # Licensed under the Apache License, Version 2.0 ( the "License" ); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. ############################################################################### import cherrypy import os from girder.constants import ROOT_DIR from ..rest import Resource, RestException """ Whenever we add new return values or new options we should increment the maintenance value. Whenever we add new endpoints, we should increment the minor version. If we break backward compatibility in any way, we should increment the major version. """ API_VERSION = "1.0.0" class ApiDocs(object): exposed = True def GET(self, **params): return cherrypy.lib.static.serve_file(os.path.join( ROOT_DIR, 'clients', 'web', 'static', 'built', 'swagger', 'swagger.html'), content_type='text/html') class Describe(Resource): discovery = { 'apis': [] } resources = {} models = {} @classmethod def param(cls, name, description, paramType='query', dataType='string', required=True): """ This helper will build a parameter declaration for you. It has the most common options as defaults, so you won't have to repeat yourself as much when declaring the APIs. """ return { 'name': name, 'description': description, 'paramType': paramType, 'dataType': dataType, 'allowMultiple': False, 'required': required } @classmethod def errorResponse(cls, reason='A parameter was invalid.', code=400): """ This helper will build an errorResponse declaration for you. Most endpoints will be able to use the default parameter values for one of their responses. """ return { 'message': reason, 'code': code } @classmethod def declareApi(cls, resource, apis): """ Rest modules should call this to document themselves. The specification can be found at: https://github.com/wordnik/swagger-core/wiki/API-Declaration. :param resource: The name of the resource, e.g. 'user' :type resource: str :param apis: The object(s) to add to the list for this resource. :type apis: list or dict """ cls.discovery['apis'].append({ 'path': '/%s' % resource }) if type(apis) is list: cls.resources[resource] = apis else: cls.resources[resource] = [apis] @Resource.endpoint def GET(self, path, params): """ Outputs the API description as a swagger-compliant JSON document. """ retVal = {} if path: resources = self.__class__.resources if path[0] in resources: retVal['apis'] = resources[path[0]] else: raise RestException('Invalid resource name "%s"' % path[0]) retVal['basePath'] = os.path.dirname( os.path.dirname(cherrypy.url())) else: retVal['basePath'] = cherrypy.url() retVal['apis'] = self.__class__.discovery['apis'] retVal['apiVersion'] = API_VERSION retVal['swaggerVersion'] = '1.2' return retVal