definitions property in swagger.json contains only stubs

[jbeard4]

Hello,

I noticed that the definitions property in the generated swagger.json seems to contain only stub objects, with a single data property of type string. This is problematic, because clients generated with swagger-codegen read the definitions property to generate model code on the client. This is particularly important for typed languages. It would be better if the definitions object were to contain complete JSON schemas for each endpoint.

Is this in-scope for the project? if I were to contribute it, would you accept a patch?

Thank you for looking into this.

[thomaxxl]

Hi,

If you can tell me what the "definitions" should look like, or how to generate them from the models, I can merge them in the swagger.
The swagger creation is kind of a mess, because it has grown "organically", and I'm not too happy with the flask_restful_swagger_2 library. I've wanted to use another library, but I never got around rewriting the code.

[jbeard4]

I will get back to you shortly on this.

[jbeard4]

Hello,

I have been doing some research, and I like the idea of using marshmallow/marshmallow-sqlalchemy for json serialization, and marshmallow-jsonschema for json-schema generation (which would be used to populate the definitions property). To elaborate, marshmallow-sqlalchemy would be used to automatically take the SQLAlchemy model and generate a Marshmallow Schema. The Marshmallow Schema is generally used for json serialization/deserialzation, and you could certainly use it for that. But you can also use the Marshmallow Schema with marshmallow-jsonschema to generate a jsonschema, which can be used to populate the definitions property. This would be a comprehensive approach, rather than an ad-hoc one, for generating the jsonschema definitions. You could also use marshmallow for serialization/deserialization of the GET/POST requests. Please let me know what you think about this approach.

I am currently looking into how to wire this up in SAFRS. I would appreciate your insight into this.

Thank you.

[thomaxxl]

Using marshmallow-sqlalchemy would be a good idea, but quite a big change.

I started with safrs before marshmallow-sqlalchemy existed, so I never used sqlalchemy for safrs, but this would be a better choice if I'd have to start over now, there's also https://github.com/marshmallow-code/marshmallow-jsonapi that could be used for jsonapi serialization, but I haven't used that either because originally, I didn't use jsonapi in safrs v1 and I just added jsonapi functionality along the way.

I think OAS "definitions" can be generated from the sqla models directly though. I'm just not familiar with the OAS definitions object.

If you'd find the time to integrate marshmallow-sqlalchemy, I'd be very happy to accept patches, but this may require quite a lot of work. I actually wanted to rewrite safrs using different libraries (marshmallow, flasgger, webargs), but since this would take at least a couple of weeks work, I never got around actually doing this. Mainly because all the functionality I need does work now.

[thomaxxl]

I've added some more models to the "definitions".
LMK if it doesn't work or you'd require more verbosity.

[OlivierPonant]

Hi @thomaxxl ,
safrs is really awesome and allows to create APIs really fast, so thanks for your work.
Sorry to dig up this old thread, but I agree with @jbeard4 the schemas generated in the swagger.json are only stubs, so it prevents to use the generated swagger.json to generate a frontend client. It's really a pity to rely on a standard format and not use its strength!

[thomaxxl]

Helllo Olivier,

I forgot about this and I will look into it when I find some time the coming weeks. I'm not too familiar with using OAS to generate client code. I prefer to use a jsonapi client library to query the api. In my experience, generated code is hard to manage, but your use case may be different.

[OlivierPonant]

Hi Thomas and thanks for your quick answer.
Maybe I missed something and I have to learn about the jsonapi paradigm ! But my wish ( and I think safrs could be able to help me with that) is to have a "server driven" client.
I mean just have to create the model on server side using sqlalchemy formalism, add these models to safrs and use its generated swagger.json and then generate the client (or at least the modelization) using the swagger.json. So the python dev I am could reduce the time spent on js/angular/react (and preserve his mental health :) ).