snimavat
commented
7 years ago @basejump I have looked at swaggydoc and Springfox and tried both.
Swaggydoc. It is based on swagger 1.2 Spec. Some what dirty implementation.. works, but broken at many things. We will need to get it working properly and maintain the project ourself. I think we can come up with better even if we did it from scratch. (We already have schema object generator)
Springfox
-
Its swagger 2.0
-
Its well mantained and has good extensibility. Most likely to be maintained and upgraged to Open API 3.0
-
The grails integration works, but not as we would want. has support for regular controllers and restful controllers. No support for generating schema properties from constraints. I am finding internal API harder to Grasp, to be able to customize to hook into Grails domain constraints. I have created an issue here https://github.com/springfox/springfox-grails-integration/issues/20 and asked for help on gitter, no definite answer yet.
-
If we get it customized to suite our needs, it can be a cleaner and better solution. However figuring out how to hook into internals to generate schema objects from domains/constraints will be difficult.
-
Note: The way our JsonSchemaGenerator is designed, it wont work with Springfox, as springfox does thing differently.
As per my current understanding of Springfox, we will probably need to do following.
- The current grails support in spring fox doesnt suit us fully with what we intend to do. It looks up all controllers regular and restful. We want to lookup just those controllers with RestAPI Annotation.
- We will need to create custom request handler provider to list just those controllers which has RestAPI annotation
- Custom property lookup to handle association $refs properly
- Custom ModelPropertyBuilder to build property definitions from constraints
- Custom ModelBuilderPlugin to set the model description from RestApi annotation
Could be few things more.
Which one do you suggest to use .. When can you be available to discuss further?
This depends on #1 being done first.
Options are
Swaggydoc
They are looking for a new maintainer. https://github.com/rahulsom/swaggydoc We can take it over, sunset the grails2 code and clean it up, upgrade to Swagger 2.0, merge my stuff in SchemaService in. I also ran a quick test and it the swaggydocs examples seem to run well. See the SwaggyDataService for how it handles associations
springfox
have not tried this yet. One of you should guys should look into it and see if you can get example working and checked in so we can see it. https://github.com/springfox/springfox-grails-demo Would need to figure out how to extend so we can merge in more domain details like I was doing in SchemaService. its not as obvious to me how to do it as it is in swaggyDoc. Springfox seems to have some momentum. might be worth reaching out and colabborating with the author to see if we can jump in and help make it better with what we are trying to do (which should really be another issue to spec out)
http://springfox.github.io/springfox/docs/current/ there seems to be a version for Grails too, https://github.com/springfox/springfox-grails-integration
Like the json-schema these will be generated for every restApiController ideally after compile and put in the resources package. Will need to look into if we do these once per pacage or do we generated 1 ibg ass file for the entire app and all controllers.