README.rst
1===========
2Flask RESTX
3===========
4
5.. image:: https://github.com/python-restx/flask-restx/workflows/Tests/badge.svg?tag=0.5.1&event=push
6 :target: https://github.com/python-restx/flask-restx/actions?query=workflow%3ATests
7 :alt: Tests status
8.. image:: https://codecov.io/gh/python-restx/flask-restx/branch/master/graph/badge.svg
9 :target: https://codecov.io/gh/python-restx/flask-restx
10 :alt: Code coverage
11.. image:: https://readthedocs.org/projects/flask-restx/badge/?version=0.5.1
12 :target: https://flask-restx.readthedocs.io/en/0.5.1/
13 :alt: Documentation status
14.. image:: https://img.shields.io/pypi/l/flask-restx.svg
15 :target: https://pypi.org/project/flask-restx
16 :alt: License
17.. image:: https://img.shields.io/pypi/pyversions/flask-restx.svg
18 :target: https://pypi.org/project/flask-restx
19 :alt: Supported Python versions
20.. image:: https://badges.gitter.im/Join%20Chat.svg
21 :target: https://gitter.im/python-restx?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
22 :alt: Join the chat at https://gitter.im/python-restx
23.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
24 :target: https://github.com/psf/black
25 :alt: Code style: black
26
27
28Flask-RESTX is a community driven fork of `Flask-RESTPlus <https://github.com/noirbizarre/flask-restplus>`_.
29
30
31Flask-RESTX is an extension for `Flask`_ that adds support for quickly building REST APIs.
32Flask-RESTX encourages best practices with minimal setup.
33If you are familiar with Flask, Flask-RESTX should be easy to pick up.
34It provides a coherent collection of decorators and tools to describe your API
35and expose its documentation properly using `Swagger`_.
36
37
38Compatibility
39=============
40
41Flask-RESTX requires Python 2.7 or 3.4+.
42
43On Flask Compatibility
44======================
45
46Flask and Werkzeug moved to versions 2.0 in March 2020. This caused a breaking change in Flask-RESTX.
47
48.. list-table:: RESTX and Flask / Werkzeug Compatibility
49 :widths: 25 25 25
50 :header-rows: 1
51
52
53 * - Flask-RESTX version
54 - Flask version
55 - Note
56 * - <= 0.3.0
57 - < 2.0.0
58 - unpinned in Flask-RESTX. Pin your projects!
59 * - == 0.4.0
60 - < 2.0.0
61 - pinned in Flask-RESTX.
62 * - >= 0.5.0
63 - All (For Now)
64 - unpinned, import statements wrapped for compatibility
65 * - trunk branch in Github
66 - All (and updated more often)
67 - unpinned, will address issues faster than releases.
68
69Installation
70============
71
72You can install Flask-RESTX with pip:
73
74.. code-block:: console
75
76 $ pip install flask-restx
77
78or with easy_install:
79
80.. code-block:: console
81
82 $ easy_install flask-restx
83
84
85Quick start
86===========
87
88With Flask-RESTX, you only import the api instance to route and document your endpoints.
89
90.. code-block:: python
91
92 from flask import Flask
93 from flask_restx import Api, Resource, fields
94
95 app = Flask(__name__)
96 api = Api(app, version='1.0', title='TodoMVC API',
97 description='A simple TodoMVC API',
98 )
99
100 ns = api.namespace('todos', description='TODO operations')
101
102 todo = api.model('Todo', {
103 'id': fields.Integer(readonly=True, description='The task unique identifier'),
104 'task': fields.String(required=True, description='The task details')
105 })
106
107
108 class TodoDAO(object):
109 def __init__(self):
110 self.counter = 0
111 self.todos = []
112
113 def get(self, id):
114 for todo in self.todos:
115 if todo['id'] == id:
116 return todo
117 api.abort(404, "Todo {} doesn't exist".format(id))
118
119 def create(self, data):
120 todo = data
121 todo['id'] = self.counter = self.counter + 1
122 self.todos.append(todo)
123 return todo
124
125 def update(self, id, data):
126 todo = self.get(id)
127 todo.update(data)
128 return todo
129
130 def delete(self, id):
131 todo = self.get(id)
132 self.todos.remove(todo)
133
134
135 DAO = TodoDAO()
136 DAO.create({'task': 'Build an API'})
137 DAO.create({'task': '?????'})
138 DAO.create({'task': 'profit!'})
139
140
141 @ns.route('/')
142 class TodoList(Resource):
143 '''Shows a list of all todos, and lets you POST to add new tasks'''
144 @ns.doc('list_todos')
145 @ns.marshal_list_with(todo)
146 def get(self):
147 '''List all tasks'''
148 return DAO.todos
149
150 @ns.doc('create_todo')
151 @ns.expect(todo)
152 @ns.marshal_with(todo, code=201)
153 def post(self):
154 '''Create a new task'''
155 return DAO.create(api.payload), 201
156
157
158 @ns.route('/<int:id>')
159 @ns.response(404, 'Todo not found')
160 @ns.param('id', 'The task identifier')
161 class Todo(Resource):
162 '''Show a single todo item and lets you delete them'''
163 @ns.doc('get_todo')
164 @ns.marshal_with(todo)
165 def get(self, id):
166 '''Fetch a given resource'''
167 return DAO.get(id)
168
169 @ns.doc('delete_todo')
170 @ns.response(204, 'Todo deleted')
171 def delete(self, id):
172 '''Delete a task given its identifier'''
173 DAO.delete(id)
174 return '', 204
175
176 @ns.expect(todo)
177 @ns.marshal_with(todo)
178 def put(self, id):
179 '''Update a task given its identifier'''
180 return DAO.update(id, api.payload)
181
182
183 if __name__ == '__main__':
184 app.run(debug=True)
185
186
187Contributors
188============
189
190Flask-RESTX is brought to you by @python-restx. Since early 2019 @SteadBytes,
191@a-luna, @j5awry, @ziirish volunteered to help @python-restx keep the project up
192and running.
193Of course everyone is welcome to contribute and we will be happy to review your
194PR's or answer to your issues.
195
196
197Documentation
198=============
199
200The documentation is hosted `on Read the Docs <http://flask-restx.readthedocs.io/en/latest/>`_
201
202
203.. _Flask: https://flask.palletsprojects.com/
204.. _Swagger: https://swagger.io/
205
206
207Contribution
208============
209Want to contribute! That's awesome! Check out `CONTRIBUTING.rst! <https://github.com/python-restx/flask-restx/blob/master/CONTRIBUTING.rst>`_
210
