Flask-Restx Swagger文档问题

Question

当我使用flask restx时，尝试为API添加额外内容时，出现AttributeError: module 'flask_restx.api' has no attribute 'doc'错误。该如何修复这个错误？

api.py

from flask import Flask
from flask_restx import Api, Resource
from hello import Hello

app = Flask(__name__)
api = Api(app)

api.add_resource(Hello, '/hello')

if __name__ == '__main__':
    app.run(debug=True)

hello.py

from flask_restx import Resource, api


@api.doc(params={'id': 'An ID'})
class Hello(Resource):
    def get(self):
        return {
            'data': {
                'names': ['one',
                          'two',
                          'three']
            }
        }

- Arul

Answer 1

我不知道你是按照哪个教程（如果有的话）学习的，但是

@api.doc(params={'id': 'An ID'})

需要一个 Api 类的实例，而不是 flask-restx.api。

通常，在教程中（至少我找到的教程），它们会展示如何在同一个文件中完成所有操作。因此，如果您的代码像下面这样编写，它将能够正常工作：

api.py

from flask import Flask
from flask_restx import Api, Resource
from hello import Hello

app = Flask(__name__)
api = Api(app)

@api.doc(params={'id': 'An ID'})
class Hello(Resource):
    def get(self):
        return {
            'data': {
                'names': ['one',
                          'two',
                          'three']
            }
        }

api.add_resource(Hello, '/hello')

if __name__ == '__main__':
    app.run(debug=True)

---

---

现在，这不是你想要实现的，因为我猜你想将文件分割成一些结构（就像我也想要的那样）。很遗憾，在网上我找不到一个合适的教程，但这是我在我的项目中所做的事情（使用你的示例代码）：

api > __init__.py

from flask_restx import Namespace

default_namespace = Namespace("default", ordered=True)

api > hello.py

from flask_restx import Resource
from api import default_namespace as ns


@ns.doc(params={'id': 'An ID'})
class Hello(Resource):
    def get(self):
        return {
            'data': {
                'names': ['one',
                          'two',
                          'three']
            }
        }

位于根目录的 app.py（你的 api.py 文件）

from flask import Flask
from flask_restx import Api
from hello import Hello
from api import default_namespace

app = Flask(__name__)
api = Api(app)

api.add_resource(Hello, '/hello')
api.add_namespace(default_namespace)

if __name__ == '__main__':
    app.run(debug=True)

包的结构在哪里：

.
+-- app.py
+-- api
   +-- __init__.py
   +-- hello.py

通过声明命名空间，您可以实际在 Swagger 中将资源组合在一起。我将命名空间放在另一个文件中（这里是__init__.py），原因是为了避免循环导入。 您可以像使用 api 一样使用所有带有 ns.doc、ns.route 等修饰符。顺便说一下，ns 是一个别名，如果您喜欢其他名称，可以在导入语句中更改它。 请注意，这可能不是最佳方法，但对于我和我的结构而言，它已经足够清洁。如果有更多经验的人知道如何以不同的方式完成此操作，请回复。

- Jeremie Magnette

Answer 2

这与@Jeremie的答案几乎相同，但我只想指向官方文档。

flask-restx中有以下语句。

Flask-RESTX提供了一种使用与Flask蓝图几乎相同的模式的方法。主要思想是将您的应用程序拆分为可重用的命名空间。

并附带一个示例：

# let's say the file name is `cat_controller`.
from flask_restx import Namespace, Resource, fields

api = Namespace('cats', description='Cats related operations')

cat = api.model('Cat', {
    'id': fields.String(required=True, description='The cat identifier'),
    'name': fields.String(required=True, description='The cat name'),
})

CATS = [
    {'id': 'felix', 'name': 'Felix'},
]

@api.route('/')
class CatList(Resource):
    @api.doc('list_cats')
    @api.marshal_list_with(cat)
    def get(self):
        '''List all cats'''
        return CATS

我们需要 add_namespace()：

from flask import Flask
from flask_restx import Api
from .cat_controller import api as ns1
from .dog_controller import api as ns2
# ...

app = Flask(__name__)
api = Api(
    app,
    version='1.0',
    title='A title',
    description='A description'
)

api.add_namespace(ns1)
api.add_namespace(ns2)

if __name__ == '__main__':
    app.run(debug=True)

- mCY