Reimplement grape-swagger on top of swagger-rb.

[antek-drzewiecki]

I would like to start a discussion about this gem's structure. At this stage this gem consist of a single file with a single method add_swagger_documentation. This methods creates a documentation class and adds all api documentation endpoints to it. At this stage all methods on api declaration, endpoints, parameters, models are in one single file now.

What is suggest is to divide logic a bit more into classes or modules with structure corresponding to the swagger spec. This has the advantage that you can separate logic into places where it belongs.
It improves readability and testability of your code. When editing the parameter module you are sure you are not accidentally editing api information. Since you have a little bit more methods defined, you might also be able to add an unit test for your method instead of only integration tests.
Last point is that variables are on their local scope, currently you can declare a variable somewhere on top and use it on line nr 200.

What do you all think of this?

[krisalyssa]

I think those are all good points. Are you volunteering to get us started? 😀

[dspaeth-faber]

👍

[dblock]

Yes, please 💯

[soulim]

I'm totally agree with this idea, and I would be very happy to start working on this.

[soulim]

Just to prevent cases when two or more people work on the same thing, it probably makes sense to explicitly "assign" this refactoring work to somebody. What do you think about that?

[dblock]

@soulim it's yours in the next 24 hours, update this issue with links to a branch with some progress if you're not done.

[soulim]

@dblock challenge accepted! 😉

[antek-drzewiecki]

Yeah, i don't have much time for this next 14 days. So its better that @soulim starts on this.
@dblock any plans for a new gem release in the near future?

[soulim]

I realised that 24 hours is not enough, because I also have to work 😉 So I'm going to work on this project on the weekend and will keep you updated.

The idea is to build wrappers around grape objects, and use interfaces of these wrappers to generate JSON response according to swagger spec. I think this approach would allow to generate JSON spec even for different versions of swagger (e.g. the swagger 2.0 is coming).

[antek-drzewiecki]

Good idea. I dont know hoe much work it is. But If it's too much work, I would start only with by extracting existing logic into responsible classes / modules. And add own specs for them. Then in the next iteration make wrappers like you are planning. Good start!

[maxlinc]

I've tried to create a generic Swagger library for Ruby:
https://github.com/swagger-rb/swagger-rb

The name is a little wonky. I didn't want to call the repo "swagger" cause I'd mix it up with every other swagger. I did want to call the gem swagger but that was taken by an unrelated project, so the gem is swagger-core. The project is young so I'm open to any and all changes - including a name change or major architectural changes.

The gem basically supports parsing, validating, traversing and building Swagger files. Right now it only supports Swagger 2.0 (both JSON or YAML) but I did try to structure it to support multiple versions: either backporting Swagger 1.2 support, or adding Swagger 2.1 or 3.0 in the future.

The builder feature is definitely the most relevant for this project.

It does lightweight validation using hashie while loading or building Swagger, and also supports full (but much slower) validation using JSON schema.

I hope this is a gem that looks like something you could use. I need swagger support for various other projects and experiments (including a Grape generator so I'm hoping to share a common library. But the project is young and I'm open to any and all changes.

If this does sound interesting, please:

• Review swagger-rb and open issues or feature requests when you have a chance
• Ping me when you're thinking about Swagger 2.0 support for this project (if you haven't done that already)

[dblock]

I think a swagger-rb library is definitely on the right track. Did you attempt to start changing grape-swagger to use it?

[calfzhou]

+1 for swagger 2.0 support

[vjm]

+1

[sunnyrjuneja]

@maxlinc I would love to put in a helping hand but it isn't clear to me where you are in the project. Is the library 100% Swagger 2.0 complaint? If so, does that mean the next step is to integrate it into grape-swagger? cc: @dblock

[dblock]

Whether swagger-rb is 2.0 compliant or not is something that can be resolved on its own. Gutting the implementation of grape-swagger would be a huge step forward, and having all tests here pass, and then we can deal with making swagger-rb whatever we want it to be.

[u2]

Great!

[dmitry]

Any roadmap, how I can contribute? What's done here and undone?

[dblock]

Nothing has been done! I say rip out the guts of this gem and keep the tests, make a PR.

[TangMonk]

+1

[LeFnord]

think this issue can be closed …
something has changed over the time
feel always welcome to improve it