- Notifications
You must be signed in to change notification settings - Fork90
A swagger 2.0 spec extractor for flask
License
getsling/flask-swagger
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
A Swagger 2.0 spec extractor for Flask
You can now specify base path for yml files:
app=Flask(__name__)@app.route("/spec")defspec():base_path=os.path.join(app.root_path,'docs')returnjsonify(swagger(app),from_file_keyword="swagger_from_file",base_path=base_path)
and use relative paths:
@app.route('/test',methods=['POST'])deflogin():""" swagger_from_file: test.yml """
Install:
pip install flask-swagger
Flask-swagger provides a method (swagger) that inspects the Flask app for endpoints that contain YAML docstrings with Swagger 2.0Operation objects.
classUserAPI(MethodView):defpost(self):""" Create a new user --- tags: - users definitions: - schema: id: Group properties: name: type: string description: the group's name parameters: - in: body name: body schema: id: User required: - email - name properties: email: type: string description: email for user name: type: string description: name for user address: description: address for user schema: id: Address properties: street: type: string state: type: string country: type: string postalcode: type: string groups: type: array description: list of groups items: $ref: "#/definitions/Group" responses: 201: description: User created """return {}
Flask-swagger supports docstrings in methods of MethodView classes (à laFlask-RESTful) and regular Flask view functions.
Following YAML conventions, flask-swagger searches for---, everything preceding is provided assummary (first line) anddescription (following lines) for the endpoint while everything after is parsed as a swaggerOperation object.
In order to support inline definition ofSchema objects inParameter andResponse objects, flask-swagger veers a little off from the standard. We require anid field for the inline Schema which is then used to correctly place theSchema object in theDefinitions object.
Schema objects can be defined in a definitions section within the docstrings (see group object above) or within responses or parameters (see user object above). We also support schema objects nested within the properties of otherSchema objects. An example is shown above with the address property of User.
If you don't like to put YAML on docstrings you can put the same content in an external file.
Create a new user---tags: -usersdefinitions: -schema:id:Groupproperties:name:type:stringdescription:the group's nameparameters: -in:bodyname:bodyschema:id:Userrequired: -email -nameproperties:email:type:stringdescription:email for username:type:stringdescription:name for useraddress:description:address for userschema:id:Addressproperties:street:type:stringstate:type:stringcountry:type:stringpostalcode:type:stringgroups:type:arraydescription:list of groupsitems:$ref:"#/definitions/Group"responses:201:description:User created
and point to it in your docstring.
classUserAPI(MethodView):defpost(self):""" Create a new user blah blah swagger_from_file: path/to/file.yml blah blah """return {}
Note that you can replaceswagger_from_file by another keyword. Supply your chosen keyword as an argument to swagger.
To expose your Swagger specification to the world you provide a Flask route that does something along these lines
fromflaskimportFlask,jsonifyfromflask_swaggerimportswaggerapp=Flask(__name__)@app.route("/spec")defspec():returnjsonify(swagger(app))
Note that the Swagger specification returned byswagger(app) is as minimal as it can be. It's your job to override and add to the specification as you see fit.
@app.route("/spec")defspec():swag=swagger(app)swag['info']['version']="1.0"swag['info']['title']="My API"returnjsonify(swag)
Swagger-UI is the reason we embarked on this mission to begin with, flask-swagger does not however include Swagger-UI. Simply follow the awesome documentation over athttps://github.com/swagger-api/swagger-ui and point yourswaggerUi.url to your new flask-swagger endpoint and enjoy.
This package now comes with a very simple command line interface: flaskswagger. This command can be used to build and update swagger specs for your flask apps from the command line or at build time.
flaskswagger -h
usage: flaskswagger [-h] [--template TEMPLATE] [--out-dir OUT_DIR] [--definitions DEFINITIONS] [--host HOST] [--base-path BASE_PATH] [--version VERSION] apppositional arguments: app the flask app to swaggerifyoptional arguments: -h, --help show this help message and exit --template TEMPLATE template spec to start with, before any other options or processing --out-dir OUT_DIR the directory to output to --definitions DEFINITIONS json definitions file --host HOST --base-path BASE_PATH --version VERSION Specify a spec versionFor example, this can be used to build a swagger spec which can be served from your static directory. In the example below, we use the manually created swagger.json.manual as a template, and output to thestatic/ directory.
flaskswagger server:app --template static/swagger.json.manual --out-dir static/
Also, you can ask flaskswagger to add host and basePath to your swagger spec:
flaskswagger server:app --host localhost:5000 --base-path /v1
Acknowledgements
Flask-swagger builds on ideas and code fromflask-sillywalk andflask-restful-swagger
Notable forks
About
A swagger 2.0 spec extractor for flask
Resources
License
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Packages0
Uh oh!
There was an error while loading.Please reload this page.