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.

score 5 · Answer 1 · answered May 27 '20 at 23:02

5

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.

answered May 27 '20 at 23:02

Pinyi Wang

823
5
14

How to document it in swagger? – leonard vertighel May 29 '22 at 10:45

score 3 · Answer 2 · answered Nov 27 '19 at 15:14

3

Try to use doc decorator instead:

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

answered Nov 27 '19 at 15:14

Ilyas

1,976
15
9

score 1 · Answer 3 · answered Feb 13 '20 at 09:06

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

score 1 · Answer 4 · answered Jun 08 '21 at 07:47

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):

Axel Anaya · Answer 5 · 2019-08-02T20:25:56.443

0

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")
})

edited Aug 02 '19 at 20:25

answered Aug 02 '19 at 19:58

Axel Anaya

122
9

no, this model says I am returning a json object {"name":"user1"}. there is no KeyValue pairs. it is simple list of strings. also I am not able to modify the api. just need to document it – user3375740 Aug 02 '19 at 20:13
Oh I got it, use `fields.List` instead of `fields.String`, I think you can't you show more than one example, but you string will be wrapped in square brackets – Axel Anaya Aug 02 '19 at 20:21
1

I think you still did not get my question, your update says this model ```{"name":["user1"]}``` by api response is ```["user1"]```, api's response is not a json – user3375740 Aug 02 '19 at 20:33
I think you can "cheat" passing it like a description in your response, for example `"['user1']"`, I see the files of RESTPlus and I can´t found a good solution for your problem – Axel Anaya Aug 02 '19 at 21:34
@AxelAnaya I'm facing the same issue. I'd like to add multiple examples in fields.List. Has anyone managed to figure out how to do this ? – franchyze923 Nov 15 '21 at 18:38

Henshal B · Answer 6 · 2021-05-18T06:08:23.397

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'

score -1 · Answer 7 · answered Nov 25 '19 at 10:46

-1

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

answered Nov 25 '19 at 10:46

Boston Kenne

778
10
15

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

7 Answers7

Step 1

Step 2

Step 3