jsonapi_rpc parameters and swagger

[wicol]

I'm trying to expose a custom endpoint related to a model. It's an endpoint for generating a new object given a value, so I created something like this:

@classmethod
@jsonapi_rpc(http_methods=["GET"])
def get_by_name(cls, name):
    """
        description : Generate and return a Thing based on name
        args:
            name:
                type : string
                example : thingy
        pageable: false
    """
    thing = cls(name=name)
    thing.description = populate_based_on_name()
    db.session.add(thing)
    db.session.commit()
    return thing.to_dict()

An endpoint is created and it does appear in the swagger ui, but the swagger docs are rather confusing; containing references to "page[offset]", "include", "sort", "filter" etc. It doesn't seem to be picking up on my docstring here.

It also seems like only one parameter, called "varargs", is supported?

Is there any way I can better control the docs generated and get a properly named parameter working? I could probably get parameters from the request instead of method args, but I'd still need to get the docs under control.

[thomaxxl]

Is there any way I can better control the docs
you can use the custom_swagger argument, eg.
https://github.com/thomaxxl/safrs/blob/master/examples/demo_pythonanywhere_com.py#L173

However, for now this can only be used to add or override existing swagger.json. It's quite tedious too atm because you have to export the swagger.json, edit it, extract the path and "feed" it back.
If you have a suggestion on how you'd like to see it implemented, I'll see what I can do.

get a properly named parameter working?
As you mention, the url query parameters are passed as **kwargs. You'll have to extract them from the kwargs dict.

[thomaxxl]

I reformatted the example, new link: https://github.com/thomaxxl/safrs/blob/master/examples/demo_pythonanywhere_com.py#L188

The swagger editor is included when you clone the repo and run this example (like in http://thomaxxl.pythonanywhere.com/swagger_editor/index.html?url=/swagger.json )

[wicol]

Alright thanks, I'll poke around some more next week and see if I can come up with a suggestion. I think just getting the docstring parsing working would get me most of the way.

[thomaxxl]

I could parse the docstring and add the arguments to swagger.
I won't get rid of the filter[] and other default arguments though.
Anyway, editing the swagger.json allows you to document your api however you want, drawback is that you'll have to update or redo it when your api changes.

GL

[wicol]

I could parse the docstring and add the arguments to swagger.

That would be great! But I think I'd need some more examples/docs as well to get the format right..

I won't get rid of the filter[] and other default arguments though.

It looks like pageable and filterable are already intended to be configurable, no? Reusing some logic from get_swagger_doc_post_arguments should take care of pageable maybe?

[thomaxxl]

Yeah, I will remove them: these parameters are supposed to be used for jsonapi responses. But the "jsonapi_rpc" is kind of a hack to implement rpc on top of jsonapi (hence the results in "meta").

On a different note, I think it's better to use POST for jsonapi_rpc most of the time for security reasons (easier to defend against csrf) but GET works.

[thomaxxl]

so, I commited something (a612c0b), but I'm not really happy about this atm.
Problem is that the swagger schema syntax for "query" arguments is different from the ones for "body" arguments, therefore, the "args" syntax is different and I have to think a bit about how to implement this consistently, because this is very confusing, eg:

    @jsonapi_rpc(http_methods=["GET"])
    def get_by_name(cls, *args, **kwargs):
        """
            description : Generate and return a Thing based on name
            args:
                - name: name
                  type: string
                  default: xx
            pageable: false
        """
        return { "result" : 1}

( https://github.com/thomaxxl/safrs/blob/master/examples/demo_pythonanywhere_com.py#L65 )

this definition is different from the "body" args in

    args:
            name:
                type : string
                example : thingy

to be continued...

[wicol]

This is great! I'm able to get a properly documented custom endpoint now :)
I agree that the differing doc structures are confusing of course, and it would be good to consolidate them. But at least it works now, so thank you for taking the time to fix it.

[thomaxxl]

v2.2.2