Idea to Enhance Documentation

[a-chacon]

Hello! I came across an introduction to your project on the Zuplo blog, and I really liked it. The way you’ve chosen to add documentation to the endpoints is very similar to what I was looking for when I created my project, OasRails. Essentially, you’ve used YARD tags to enhance the documentation and display it as an OAS, which is exactly what I did.

Since your framework is quite similar to Rails (I apologize, but I haven't looked at the code in depth), I was wondering if OasRails might also work with your project. Perhaps you could delegate the task of documenting to OasRails engine. I'm not sure if this would work, but I am available to explore it.

Just wanted to share the idea—if you’d prefer not to rely on external tools for documentation, I completely understand. Keep up the great work, and best of luck!

[rsamoilov]

Hey Andrés,

Your project looks great!

I'm generally open to using OasRails to build OpenAPI documentation if it proves to be more advanced than the current solution.

Have you tried using your project with Rage? Does it require any Rails public APIs that Rage would also need to implement to support it?

[a-chacon]

Good! I will try OasRails on Rage and tell you if it works or may work ;)

[a-chacon]

hey @rsamoilov I finally split my gem into a core logic and the Rails adapter. So I can integrate the core with other frameworks like yours.

I made a quick gem to test it, take a look here: https://github.com/a-chacon/oas_rage

It works, but is not compatible with your tags. You can take a look into the dummy rage app that I used for testing, clone it, go to the rage app, install dependencies and run the bundle exec rage s. Also, I tested it with the to-do app, but you must remove the tags for making it works.

Let me know if you like it and maybe in a future we can enhance the integration with Rage!

[rsamoilov]

Hey @a-chacon , sorry for the delay!

I love what you've done with your gem. The idea of having the core and framework-specific adapters separately makes perfect sense to me.

Unfortunately, the incompatibility with the current tags is a problem. Will you continue working on oas_rage?

[a-chacon]

Don't worry. I pretend to keep the adapters updated in respect to the OasCore version, so in respect to OasRage I will update it to version 1.0.0 to support of the references in tags and just that for now. Then, If I notice interest, I can continue working on it.

I know that the incompatibility of the tags can be a problem for existing apps. If you want, you can offer this gem just as an alternative of the default implementation.

Change the tags will break the others adapters, so it is not an alternative for now.