Swagger documentation and roda route lists

[J Danielian]

I have been using Roda for some micro services for awhile now, and absolutely love it. I have done some integration using the swagger-blocks gem to document the request and response bodies of various REST API endpoints. What I have put together for my services works, but would love to formalize it a bit and make a plugin for it. 

I was thinking of extending off of the current list-routes plugin to build up the swagger endpoints list. However, I would need to add two things to that parser so that I could know the request body DTO object and response body DTO object (if applicable).

Currently, that guy looks for comments in the routes like this => # route: GET|POST /path/to/foo/:foo_id

I would need to modify it to do something like # route: GET|POST /path/to/foo/:foo_id request: Path::To::DTO::Class response: Path::To::Class

Then the parse action could build up the metadata routes and also parse out the request and response bodies so we know what the "contract" looks like for the endpoint.  The only other minimum thing needed would be an ability to describe HTTP status codes coming back. That would be a barebones implementation. Obviously, a complete solution would have security/authentication information, description that could be entered for swagger, etc, etc. So, there is a balance to where its starting to be too much to handle just using inline comments. :) I have thought about using a yaml file to handle these route properties instead of inline, but that gets messy linking the two together.

Any thoughts out there on the best way to approach this? Also, is it possible to create a plugin that depends on another plugin? Or is it best to just fork the existing plugin and add extra functionality to the existing one? Would anyone have interest in this? Is there a gem that is doing this (in an automated way) that I missed?

Sorry for all the questions, I am kind of a noob in terms of contributing. I have some time over the next few weeks, and would love to figure out a way to contribute to this great tool. 

Thanks!

J

[Tim Uckun]

Isn't it just as easy to just create the yaml file and use swagger codegen? 

--
You received this message because you are subscribed to the Google Groups "Roda" group.
To unsubscribe from this group and stop receiving emails from it, send an email to ruby-roda+unsubscribe@googlegroups.com.
To post to this group, send email to ruby...@googlegroups.com.
Visit this group at https://groups.google.com/group/ruby-roda.
To view this discussion on the web visit https://groups.google.com/d/msgid/ruby-roda/ec3074da-9280-4fcd-bcba-d7f3f8358b42%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[J Danielian]

Is there a way to not have to manually build up and maintain the YAML file though? That is where I was thinking if I could tie into the route list plugin, it would help from having to manually build and maintain the YAML file. Using swagger blocks, I have to maintain a list of the routes - this is the part I was trying to automate. But, perhaps that just isn't realistic when looking at all the options you might want to document via swagger.

On Monday, October 23, 2017 at 9:29:18 AM UTC-4, Tim Uckun wrote:

Isn't it just as easy to just create the yaml file and use swagger codegen? 

On Tue, Oct 24, 2017 at 2:25 AM, J Danielian <jaydan...@gmail.com> wrote:

I have been using Roda for some micro services for awhile now, and absolutely love it. I have done some integration using the swagger-blocks gem to document the request and response bodies of various REST API endpoints. What I have put together for my services works, but would love to formalize it a bit and make a plugin for it. 

I was thinking of extending off of the current list-routes plugin to build up the swagger endpoints list. However, I would need to add two things to that parser so that I could know the request body DTO object and response body DTO object (if applicable).

Currently, that guy looks for comments in the routes like this => # route: GET|POST /path/to/foo/:foo_id

I would need to modify it to do something like # route: GET|POST /path/to/foo/:foo_id request: Path::To::DTO::Class response: Path::To::Class

Then the parse action could build up the metadata routes and also parse out the request and response bodies so we know what the "contract" looks like for the endpoint.  The only other minimum thing needed would be an ability to describe HTTP status codes coming back. That would be a barebones implementation. Obviously, a complete solution would have security/authentication information, description that could be entered for swagger, etc, etc. So, there is a balance to where its starting to be too much to handle just using inline comments. :) I have thought about using a yaml file to handle these route properties instead of inline, but that gets messy linking the two together.

Any thoughts out there on the best way to approach this? Also, is it possible to create a plugin that depends on another plugin? Or is it best to just fork the existing plugin and add extra functionality to the existing one? Would anyone have interest in this? Is there a gem that is doing this (in an automated way) that I missed?

Sorry for all the questions, I am kind of a noob in terms of contributing. I have some time over the next few weeks, and would love to figure out a way to contribute to this great tool. 

Thanks!

J

--
You received this message because you are subscribed to the Google Groups "Roda" group.

To unsubscribe from this group and stop receiving emails from it, send an email to ruby-roda+...@googlegroups.com.

[Tim Uckun]

Looking at the swagger blocks examples the YAML takes less key strokes to type. 

Having said that version three of swagger seems insane to me.

To view this discussion on the web visit https://groups.google.com/d/msgid/ruby-roda/8fd41ab4-9ae8-42e7-981a-11088e32c820%40googlegroups.com.

[Jeremy Evans]

It's completely possible to create a plugin that depends on another plugin, there's specific support for this by having load_dependencies singleton method in the plugin.

You could also fork the roda-route_list plugin and add the extra functionality.  I'm not sure how much more you need in terms of features, but as long as you feel comfortable maintaining the fork, that should be fine.

Unfortunately, I have no experience with swagger/OpenAPI and no desire to gain experience with it considering the opportunity cost, so I don't think I'd be able to help with swagger/OpenAPI specific issues.

Thanks,

Jeremy

[christian meier]

me 2 cents about roda+swaggger: the first thought was the route-list plugin but this is not really feasible for us. so we write a test for each point using a custom DSL which produces on the fly the swagger.json. as we use dry-validation for processing the request param we also use this validation schema to produce detailed params info for swagger. altogether it is really DRY and tested but the downside is that the tests generate the swagger.json file which needs to be included into the git repo.

[Bougy Man (bougyman)]

This is my third time finding this thread in a Google search, so I'd like to reopen the discussion. I would prefer not to have a swagger mandate, but they keep occurring and I'd like to find a repeatable solution. We use yard for documentation already, so using swagger_yard to generate the swagger docs seems the least intrusive. We're experimenting with that this week, will reply to this thread with our results.

[Bougy Man (bougyman)]

I'm sure there is a more elegant way to do this, but we have a working api with automatic openapi/swagger documentation, utilizing swagger_yard with this monkey patch: https://gist.github.com/bougyman/4be2401570f7a621c2fe4df7e1b219f1.

Now our routes files simply look like `r.get 'some_route' { some_method r  }` where some_method is defined in a module living in `lib/payments/route_methods/some_module.rb`, and that method has the swagger_yard tags which are used by swagger_yard to generate the specification file.

Hope this helps someone, and we will look to improve on this going forward.

Tj