How to document a flask-restplus response with list of strings

Question

I am documenting my response models, and need to show the api returns list of string.

["user1","user2"]

but the model requires a dictionary(json) format, as follow:

ns.response(200,'Success', NS.model("my_get_model",[{
    "name": fields.String(example="user1"),
}]))

I have tried following codes but none of them work:

ns = Namespace('My Apis')


ns.response(200,'Success', [ns.model("my_get_model",
    fields.String(example="user1")
)])

or

ns.response(200,'Success', ["user1"])

or

ns.response(200,'Success', ns.model("my_get_model",fields.List(fields.String(example="user1"))))

Please advice.

Answer 1

I think this is what you need: https://github.com/python-restx/flask-restx/issues/65

Try simply passing in fields.List without wrapping a model.

ns.response(200, 'Success', fields.List(fields.String(example="user1")))

FYI, flask-restx is a fork of flask-restplus and it should have more updated features since flask-restplus is no longer being maintained due to the developers no able to contact flask-restplus 's project owner.

Answer 2

尝试改用 doc 装饰器：

@api.doc(responses={200: """['s1', 's2', 's3']"""})

Answer 3

Here is the example, How to use model with the response:

from flask_restplus import Namespace, fields
Import <other packges>

NS = Namespace(name="Api Name", description="Api description")

# Model
MY_MODEL = NS.model(
    "mymodel",
    {
        "message": fields.String(example="some string"),
        "some_code": fields.String(example="SOME_CODE_101"),
        "some_list_params": fields.List(fields.String)
    },
)

# For controller

@NS.route("hello")
class Hello(Resource):
    """Some API"""

    def __init__(self, *args, **kwargs):
        super(Hello, self).__init__(*args, **kwargs)

    @NS.vendor(private=True)
    @NS.response(200, "My API", MY_MODEL)
    @marshal_with(MY_MODEL)
    def get(self):

        return {some_code: "SOME_CODE_101", "message": "Some message", "some_list_params": []}, 200

Here you can use the fields.List

Answer 4

I think the structure of you model is wrong, you need to write in this way:

ns.model("my_get_model",{
    "name": fields.String(example="user1")
})

UPDATE: Showing a list like a value of a key in your JSON you needs to use fields.List instead of fields.String

ns.model("my_get_model",{
    "name": fields.List(example="user1")
})

Answer 5

At first, flask-restplus is moved to flask-restx. Check it out .

Step 1

Define model as an instance or as an attribute to api or ns.

model = model("ModelName",{"name": fields.String(example="user1")})

Step 2

Define instance of Api or Namespace.

api = Api(app) #or
ns = Namespace('NamespaceName')

Step 3

Append response decorator to endpoint.

@api.response(200, model, as_list=True) #or ns
def get(self):
    return 'Your response'

Answer 6

Found in https://flask-restx.readthedocs.io/en/latest/swagger.html

Tested with flask-restx==0.2.0

    dbsystem_fields = ns.model('DbSystem', {
        'id': fields.String,
        'name': fields.String,
        'engine': fields.String,
        'version': fields.String
    })
    
    @ns.route('/systems')
    class Systems(Resource):
        @ns.marshal_with(dbsystem_fields, as_list=True)
    
    @api.route('/systems')
    class Systems(Resource):
        @api.marshal_with(dbsystem_fields, as_list=True)
        # @api.response(200, "Success", [dbsystem_fields]) # Also works
        def get(self):

Answer 7

Try to make your model like this, when you are using model , you have to use enum instead of List

ns.model("my_get_model",{
    "name": fields.String(description="your description", enum=["user1", "user2"])
})

Hope it'll help you, let me know