Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Swagger documentation parameters issue with several routes #164

Closed
ziirish opened this issue Apr 22, 2016 · 2 comments
Closed

Swagger documentation parameters issue with several routes #164

ziirish opened this issue Apr 22, 2016 · 2 comments

Comments

@ziirish
Copy link
Collaborator

@ziirish ziirish commented Apr 22, 2016

Hi,

As stated in #146, I have a swagger documentation issue when I have several routes for the same resource.

The example given was a special case (with methods=['GET']) but with a normal case I encounter the same issue.

Here is an extract:

@ns.route('/stats/<name>',                                                      
          '/<server>/stats/<name>',                                             
          endpoint='client_stats')
class ClientStats(Resource):                                                    
    """The :class:`burpui.api.client.ClientReport` resource allows you to          
    retrieve a list of backups for a given client.                              

    This resource is part of the :mod:`burpui.api.client` module.               

    An optional ``GET`` parameter called ``serverName`` is supported when          
    running in multi-agent mode.                                                
    """                                                                         
    parser = api.parser()                                                       
    parser.add_argument(                                                        
        'serverName',                                                           
        help='Which server to collect data from when in multi-agent mode'          
    )                                                                           
    client_fields = api.model('ClientStats', {                                  
        'number': fields.Integer(required=True, description='Backup number'),   
        'received': fields.Integer(required=True, description='Bytes received'),
        'size': fields.Integer(required=True, description='Total size'),        
        'encrypted': fields.Boolean(                                            
            required=True,                                                      
            description='Is the backup encrypted'                               
        ),                                                                      
        'deletable': fields.Boolean(                                            
            required=True,                                                      
            description='Is the backup deletable'                               
        ),                                                                                                       
        'date': fields.DateTime(                                                
            required=True,                                                      
            dt_format='iso8601',                                                
            description='Human representation of the backup date'               
        ),                                                                      
    })                                                                          

    @api.cache.cached(timeout=1800, key_prefix=cache_key)
    @ns.marshal_list_with(client_fields, code=200, description='Success')
    @ns.expect(parser)
    @ns.doc(                                                                    
        params={                                                                
            'server': 'Which server to collect data from when in multi-agent' + 
                      ' mode',                                                  
            'name': 'Client name',                                              
        },                                                                      
        responses={                                                             
            '403': 'Insufficient permissions',                                  
            '500': 'Internal failure',                                          
        },                                                                      
    )
    def get(self, server=None, name=None):                                      
        """Returns a list of backups for a given client                         

        **GET** method provided by the webservice.                              

        The *JSON* returned is:                                                 
        ::                                                                      

            [                                                                                   
              {                                                                 
                "date": "2015-01-25 13:32:00",                                  
                "deletable": true,                                              
                "encrypted": true,                                              
                "received": 123,                                                
                "size": 1234,                                                   
                "number": 1                                                     
              },                                                                
            ]                                                                   

        The output is filtered by the :mod:`burpui.misc.acl` module so that you 
        only see stats about the clients you are authorized to.                 

        :param server: Which server to collect data from when in multi-agent    
                       mode                                                     
        :type server: str                                                       

        :param name: The client we are working on                               
        :type name: str                                                         

        :returns: The *JSON* described above.                                   
        """                                                                     
        [...]
        return j

And here is the associated swagger.json extract:

        "/client/stats/{name}": {
            "get": {
                "description": "**GET** method provided by the webservice.\n\nThe *JSON* returned is:\n::\n\n    [\n      {\n        \"date\": \"2015-01-25 13:32:00\",\n        \"deletable\": true,\n        \"encrypted\": true,\n        \"received\": 123,\n        \"size\": 1234,\n        \"number\": 1\n      },\n    ]\n\nThe output is filtered by the :mod:`burpui.misc.acl` module so that you\nonly see stats about the clients you are authorized to.\n\n:param server: Which server to collect data from when in multi-agent\n               mode\n:type server: str\n\n:param name: The client we are working on\n:type name: str\n\n:returns: The *JSON* described above.", 
                "operationId": "get_client_stats", 
                "parameters": [
                    {
                        "description": "Which server to collect data from when in multi-agent mode", 
                        "in": "query", 
                        "name": "serverName", 
                        "type": "string"
                    }, 
                    {
                        "description": "Client name", 
                        "in": "path", 
                        "name": "name", 
                        "required": true, 
                        "type": "string"
                    }, 
                    {
                        "description": "Which server to collect data from when in multi-agent mode", 
                        "in": "query", 
                        "name": "server", 
                        "type": "string"
                    }, 
                    {
                        "description": "An optional fields mask", 
                        "format": "mask", 
                        "in": "header", 
                        "name": "X-Fields", 
                        "type": "string"
                    }
                ], 
                "responses": {
                    "200": {
                        "description": "Success", 
                        "schema": {
                            "items": {
                                "$ref": "#/definitions/ClientStats"
                            }, 
                            "type": "array"
                        }
                    }, 
                    "403": {
                        "description": "Insufficient permissions"
                    }, 
                    "500": {
                        "description": "Internal failure"
                    }
                }, 
                "summary": "Returns a list of backups for a given client", 
                "tags": [
                    "client"
                ]
            }, 
            "parameters": [
                {
                    "in": "path", 
                    "name": "name", 
                    "required": true, 
                    "type": "string"
                }
            ]
        }, 
"/client/{server}/stats/{name}": {
            "get": {
                "description": "**GET** method provided by the webservice.\n\nThe *JSON* returned is:\n::\n\n    [\n      {\n        \"date\": \"2015-01-25 13:32:00\",\n        \"deletable\": true,\n        \"encrypted\": true,\n        \"received\": 123,\n        \"size\": 1234,\n        \"number\": 1\n      },\n    ]\n\nThe output is filtered by the :mod:`burpui.misc.acl` module so that you\nonly see stats about the clients you are authorized to.\n\n:param server: Which server to collect data from when in multi-agent\n               mode\n:type server: str\n\n:param name: The client we are working on\n:type name: str\n\n:returns: The *JSON* described above.", 
                "operationId": "get_client_stats", 
                "parameters": [
                    {
                        "description": "Which server to collect data from when in multi-agent mode", 
                        "in": "query", 
                        "name": "serverName", 
                        "type": "string"
                    }, 
                    {
                        "description": "Client name", 
                        "in": "path", 
                        "name": "name", 
                        "required": true, 
                        "type": "string"
                    }, 
                    {
                        "description": "Which server to collect data from when in multi-agent mode", 
                        "in": "path", 
                        "name": "server", 
                        "required": true, 
                        "type": "string"
                    }, 
                    {
                        "description": "An optional fields mask", 
                        "format": "mask", 
                        "in": "header", 
                        "name": "X-Fields", 
                        "type": "string"
                    }
                ], 
                "responses": {
                    "200": {
                        "description": "Success", 
                        "schema": {
                            "items": {
                                "$ref": "#/definitions/ClientStats"
                            }, 
                            "type": "array"
                        }
                    }, 
                    "403": {
                        "description": "Insufficient permissions"
                    }, 
                    "500": {
                        "description": "Internal failure"
                    }
                }, 
                "summary": "Returns a list of backups for a given client", 
                "tags": [
                    "client"
                ]
            }, 
            "parameters": [
                {
                    "in": "path", 
                    "name": "name", 
                    "required": true, 
                    "type": "string"
                }, 
                {
                    "in": "path", 
                    "name": "server", 
                    "required": true, 
                    "type": "string"
                }
            ]
        }, 

The full code is available here

The swagger is available here (login: admin / admin )

Thanks

@ziirish

This comment has been minimized.

Copy link
Collaborator Author

@ziirish ziirish commented Jul 13, 2016

Up?

selection_022

@ns.route('/archive/<name>/<int:backup>',                                       
          '/<server>/archive/<name>/<int:backup>',                              
          endpoint='async_restore')
class AsyncRestore(Resource):                                                   
    """The :class:`burpui.api.restore.AsyncRestore` resource allows you to         
    perform a file restoration.                                                 

    This resource is part of the :mod:`burpui.api.restore` module.              

    The following parameters are supported:                                     
    - ``list``: list of files/directories to restore                            
    - ``strip``: number of elements to strip in the path                        
    - ``format``: returning archive format                                      
    - ``pass``: password to use for encrypted backups                           
    """                                                                         
    parser = ns.parser()                                                        
    parser.add_argument('pass', help='Password to use for encrypted backups', nullable=True)
    parser.add_argument('format', required=False, help='Returning archive format', choices=('zip', 'tar.gz', 'tar.bz2'), default='zip', nullable=True)
    parser.add_argument('strip', type=int, help='Number of elements to strip in the path', default=0, nullable=True)
    parser.add_argument('list', required=True, help='List of files/directories to restore', nullable=False)

    @ns.expect(parser, validate=True)
    @ns.doc(                                                                    
        params={                                                                
            'server': 'Which server to collect data from when in multi-agent mode',
            'name': 'Client name',                                              
            'backup': 'Backup number',                                          
        },                                                                      
        responses={                                                             
            200: 'Success',                                                     
            400: 'Missing parameter',                                           
            403: 'Insufficient permissions',                                    
            500: 'Internal failure',                                            
        },                                                                      
    )
    def post(self, server=None, name=None, backup=None): 
@miszczu

This comment has been minimized.

Copy link

@miszczu miszczu commented Aug 16, 2016

@ziirish , I had similar issue but with one route, to get rid of duplicated params I had to document path parameters on resource level instead of method level.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
2 participants
You can’t perform that action at this time.