项目作者: plainas

项目描述 :
A swagger spec generator and type checker for flask
高级语言: Python
项目地址: git://github.com/plainas/flask-swagger-types.git
创建时间: 2019-10-02T00:47:02Z
项目社区:https://github.com/plainas/flask-swagger-types

开源协议:

下载


Flask-swagger-types

Flask-swagger-types is a swagger spec generator and type checker for flask applications. Define marshmallow schemas for your input data and responses, anotate your routes with @FlaskSwaggerTypes.Fstroute() using these schemas, and get a swagger spec free at [YOUR_APP_URL]/swagger_spec.

Swagger_ui is exposed for convenience at [YOUR_APP_URL]/swagger_ui.

No hand written swagger spec chunks or monster docstrings non-sense. Your swagger spec is generated from your application semantics. Why wouldn’t it, really?

@FlaskSwaggerTypes.Fstroute() calls flask’s own @flask.route() under the hood, so all of Flask’s funcionality is preserved and you can mix both anotations in the same application. This is usefull if you want to expose only a subset of your application rules in your swagger spec.

Flask-swagger-types is not a flask plugin. It is just a tiny helper with a single anotation definition.

Installation

  1. pip3 install https://github.com/plainas/flask-swagger-types/zipball/master

Example app:

  1. from flask import Flask, request, make_response, Response
  2. import marshmallow
  3. import pkg_resources
  4. from flaskswaggertypes import FlaskSwaggerTypes
  5. # 1. Define some general info you want included in your spec.
  6. spec_metadata = {
  7. 'title': "My fancy web api",
  8. 'description': "Does some fancy api stuff on my fancy api-y server" ,
  9. #'basePath': "/sofancy/", #(optional)
  10. 'version': "33",
  11. #'host': "fancy.example.com" #(optional)
  12. }
  13. # 2. Define some marshmallow schemas
  14. class Pants(marshmallow.Schema):
  15. _id = marshmallow.fields.Int()
  16. name = marshmallow.fields.String()
  17. brand = marshmallow.fields.String()
  18. size = marshmallow.fields.Int()
  19. # You can define collections by nesting an existing type with Nested()
  20. class PantsList(marshmallow.Schema):
  21. pants = marshmallow.fields.Nested(Pants, many=True)
  22. # responses are defined like so:
  23. responses = [
  24. [ 200 , "Server will reply with 200 to successfull calls" ],
  25. [ 400 , "Just mentioning that calls to this api method could go south"],
  26. ]
  27. # you can optionally pass the response Schema
  28. responses_with_type = [
  29. [ 200 , "Server will reply with 200 to successfull calls", PantsList ],
  30. [ 400 , "Server will repply with 400 if it rails to retrieve a list of pants" ],
  31. ]
  32. # 3. Create your flask app as usual
  33. app = Flask(__name__)
  34. # 4. Initialize flask-swagger-types
  35. fst = FlaskSwaggerTypes(app, spec_metadata)
  36. # 5. Define some routes with @Fstroute()
  37. @fst.Fstroute('/savePants', "POST", {'body' : Pants }, responses)
  38. def saveYourFancyPants():
  39. # Parsed and validated data will be available at
  40. print(request.fst_data)
  41. #...
  42. return "Success!!!"
  43. # path paramters are parsed and will automatically show up in your swagger spec
  44. # without the need to manually pass its schema.
  45. @fst.Fstroute('/getManyPants/<int:size>/<string:brand>', "GET", {}, responses )
  46. def getManyFancyPants(size, brand):
  47. print(request.fst_data)
  48. # ...
  49. return "your pants list here"
  50. @fst.Fstroute('/getFancyPants', "GET", {}, responses_with_type)
  51. def getFancyPants():
  52. pantslistschema = PantsList()
  53. empty_list = pantslistschema.dumps([])
  54. return empty_list
  55. # 6. Start your flask app as usual
  56. app.run()
  57. # Your swagger spec can now be accessed at [YOUR_APP_URL]/swagger_spec
  58. # To browse your api with swager-ui, go to [YOUR_APP_URL]/swagger_ui?url=/swagger_spec#/default

Api reference

  1. #TODO.
  2. The sample app should cover what you need. If not, read the source. It's less than 200 lines of code.