Allow for definitions outside of parameters and responses

[atlithorn]

One idea would be to provide a directory path to swagger in which to search for definitions in docstrings of models

[atlithorn]

Also consider marshalled objects which are often vastly different to models and easily translated to definitions without docstrings

[ShiftyMcCool]

I know I'm late to the game here, but I would love to know how to create definitions outside of parameters and responses and reference them with $ref. It's pretty much the only thing getting in my way using this.

[atlithorn]

Not late to the game at all. I just haven't had reason to explore this in my own projects because responses and parameters have done fine.

Do you have any ideas for where you would like to read the definitions from?

[ShiftyMcCool]

Wow, thanks for the fast response. It would be nice to be able to reference a separate YAML/JSON file(s) or URL, but having a special comment block that's used by the plugin (like it currently does) would work too.

BTW, great plugin! Super easy to set up!

[atlithorn]

I actually wasn't aware that one could use $ref for external json files but this would seem to indicate that it should "just work" https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#reference-object

If swagger-ui supports it then you should be able to do this as is with flask-swagger, just like you can reference existing definitions eg.

parameters:
  - name: body
    in: body
    schema:
      $ref: "#/definitions/Session"

So again, I haven't tested this but according to the docs this should just work if you provide a definitions.json file from the same location as your spec

parameters:
  - name: body
    in: body
    schema:
      $ref: "definitions.json#/Session"

Regarding the special comment block, that's what I can't get my head around where I would place. Flask-Swagger inspects the app for the endpoints but I'm not sure where would be a "standard flask" placement for standalone definitions. Maybe it could just be an optional parameter to the swagger method?

[ShiftyMcCool]

Thanks again for the quick response. I've tried referencing an external file like that but, either my relative path is wrong (Python has an odd idea of directory locations... and I'm just beyond being a Python novice), or my definitions aren't getting added to the swagger output for some other reason (the definitions block is empty).

For this block:
schema:
type: object
properties:
category:
type: array
items:
$ref: "definitions.yaml#/Category"
match_count:
type: integer
message:
type: string
enum:
- Success

Swagger UI shows me this (notice the null):
{
"category": [
null
],
"match_count": 0,
"message": "Success"
}

[atlithorn]

I'll try to test external definitions myself sometime soon, not quite sure I follow what you're trying to do.

[ShiftyMcCool]

Sorry, I'll try to explain a bit better.

When flask-swagger does its thing, any schemas that are added in the comment block are replaced with references to objects in definitions. So this YAML:

schema:
  id: Data
  type: object
  properties:
    data_value:
      type: string

Would create swagger JSON like this:

"definitions": {
    "Data": {
      "properties": {
        "data_value": {
          "type": "string"
        }
      }, 
      "type": "object"
    }
  }

And a reference like this:

...
"schema": {
   "$ref": "#/definitions/Data"
 }
...

The problem is that any external references like $ref: "definitions.yaml#/Data" don't end up in the "definitions": {} so anything parsing the generated JSON gets a null reference like my code in the previous comment. I'm not sure if this is the way it is supposed to work, but it seems that flask-swagger should follow the external reference, add the object to the definitions block and update the $ref to be local (#/definitions/Data).

Does that make any more sense?

[atlithorn]

That makes sense.

Since there are multiple places where users could place their external YAML or JSON definitions I have been leaning towards simply pointing out that users could simply parse the external definitions themselves and extend the definitions object generated by flask-swagger ( much like the README shows with swagger['info']['version'] = ... ) and then use local references as normal.

Your idea would however be a nice trick - if flask-swagger finds a reference that is "external" ( not really external since it has to be relative to the running process current directory ) it could try to open the YAML or JSON file and add the corresponding schema definition to the definitions object if it succeeds.

I can't promise when I will have the time to explore that but as always feel free to have a crack at it yourself and send me a PR.