Comments (9)
Also consider marshalled objects which are often vastly different to models and easily translated to definitions without docstrings
from flask-swagger.
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.
from flask-swagger.
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?
from flask-swagger.
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!
from flask-swagger.
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?
from flask-swagger.
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"
}
from flask-swagger.
I'll try to test external definitions myself sometime soon, not quite sure I follow what you're trying to do.
from flask-swagger.
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?
from flask-swagger.
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.
from flask-swagger.
Related Issues (20)
- Doc example showing root level definitions? HOT 1
- Are Blueprint supported ? HOT 9
- Pip source code is different from github master branch HOT 2
- Multiple path parameters and multiple endpoints HOT 3
- Add partial substitution of docstrings -- expansion of .yml file support HOT 5
- Spec throws exception on bad yaml HOT 1
- Swagger UI v3 HOT 2
- Support resuableParameters
- yaml file location HOT 2
- Support flask blueprint
- Passing Absolute YAML Path In Windows HOT 1
- pip install missing packages
- Supported methods to authenticate and cache web token
- Support for "securityDefinitions" HOT 3
- AttributeError: type object 'Create' has no attribute 'lower' HOT 1
- TypeError: swagger() got an unexpected keyword argument 'base_path'
- Type annotations / type hints / stub files for mypy HOT 4
- [Question] Can I check flask-swagger comments for correctnes?
- 'base_path' argument error HOT 3
- Invalid path parameter HOT 2
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from flask-swagger.