Support for "securityDefinitions"

[SandhyaGiri]

Currently even though "securityDefinitions" section is provided in the documentation for the API, it is not reproduced in the final JSON produced.

Sample Documentation on a API method (with securityDefinitions section)

@app.route('/reports', methods=["POST"])
def sample_meth():
       """
       Uploads the given file to servers.
        ---
        securityDefinitions:
          BasicAuth:
            type: "basic"
        definitions:
          - schema:
            id: ErrorResponse
            properties:
              error:
                type: "string"
                description: "Gives a description about the error."
            example:
              error: "Lab name is not provided."
        operationId: "uploadReport"
        security:
          - BasicAuth: []
        """
        print("sample meth")

Expected JSON response

Following definition should be present at the root level of the JSON generated.

"securityDefinitions": {
    "BasicAuth": {
      "type": "basic"
    }
  }

Actual JSON response

Carries only the security requirement for the corresponding path, and the 'securityDefinitions' section is missing.

{ 
   "definitions":{ 
      "ErrorResponse":{ 
         "example":{ 
            "error":"Lab name is not provided."
         },
         "properties":{ 
            "error":{ 
               "description":"Gives a description about the error.",
               "type":"string"
            }
         }
      }
   },
   "paths":{ 
      "/reports":{ 
         "post":{ 
            "security":[ 
               { 
                  "BasicAuth":[ 

                  ]
               }
            ],
            "summary":"Uploads the given file to servers."
         }
      }
   }
}

Current solution is to add it manually to the generated JSON object, like below:

from flask_swagger import swagger
@app.route("/spec")
def spec():
     swag_doc = swagger(app)
     swag_doc['securityDefinitions'] = {"BasicAuth": {"type": "basic"}}

[mrname]

IMO, your current solution seems like the most reasonable way to accomplish this. Defining the base securityDefinitions inside of your docstrings does not fully make sense, as they should only be defined once at the base and then referenced inside your docstrings.

In that case, some clarification/examples in the docs might help. If this is insufficient for your needs, can you elaborate more on how you would like to see this working?

[SandhyaGiri]

The current solution is perfectly fine for me. But what I had in my mind, was to extract these securityDefinitions from the docstrings of any method to the top level, just like what is currently being done for definitions. Do you think this makes sense?

[mrname]

Thanks @SandhyaGiri this definitely makes sense. I think I'm just trying to reason about conflict resolution in the event that there are two different security definitions with the same name. For example:

@app.route('/reports', methods=["POST"])
def sample_meth():
       """
       docstring
        ---
        securityDefinitions:
          ApiKeyAuth:
            type: apikey
            in: header
            name: X-API-Key

and then another view:

@app.route('/reports', methods=["POST"])
def sample_meth():
       """
       docstring
        ---
        securityDefinitions:
          ApiKeyAuth:
            type: apikey
            in: header
            name: X-API-Key-Different-Header

In this case, which definition would we expect to see in securityDefinitions? More importantly, which one would be used for the view?

The thing I like about your solution is that there is one and only one way to define the security definitions.

It looks like definitions gets handled by requiring an ID, so we could consider doing something similar with securityDefinitions if we want to.