search

andrenth / ocaml-swagger

Swagger 2.0 code generator for OCaml
37 stars 10 forks source link

Expose the Swagger_t and Swagger_j modules #20

Closed carlosdagos closed 3 years ago

carlosdagos commented 5 years ago

Alternative to #19 as discussed with @rizo.

Separate the codegen function into two separate functions: One for parsing the API definitions, and one to generate the code from the parsed data.

Keep the original function as a convenience function.

README updated accordingly.

rizo commented 5 years ago

I like this approach. @rdavison, do you have any thoughts about this?

We might consider cleaning the public interface a bit before releasing, but I think this is a good start.

rdavison commented 5 years ago

I think it's a great idea to expose those Swagger modules! The only concern I have is that functions in swagger.ml are somewhat awkwardly named.

For instance, val codegen_of_swagger is misleading, as there is no type codegen in the module. In that case, I would probably just rename the function to val codegen_swagger, or even something more descriptive such as codegen_swagger_to_string, as that would imply that codegen is a verb, not a noun.

However, as an alternative approach, you could define a type codegen = string. That way, val codegen_of_swagger could make sense, but then I would rename val codegen to val output_codegen to show that it is performing a side effect instead of just producing a value of type codegen.

carlosdagos commented 5 years ago

Thanks for your feedback @rizo and @rdavison.

I chose to go with the function name codegen_swagger_to_string. I think it's clearer as well 👍

carlosdagos commented 5 years ago

Any update @rizo? Thanks!

rizo commented 4 years ago

Hey, @carlosdagos! Apologies for the delay. I haven't been actively using swagger for a long time now.

Recently I had a need to construct a swagger spec for an API and implemented this: https://github.com/andrenth/ocaml-swagger/pull/23

It's very similar to your approach but, in addition to exposing the modules, provides documentation and value constructors. There are many optional fields in the schema, so having functions with default values is a huge improvement.

I intentionally didn't change the existing codegen function to keep compatibility. I would be happy to change it similar to how you did it in your PR.

Let me know your thoughts on this. And apologies for such a late reply again...

carlosdagos commented 3 years ago

Thanks @rizo! Happy to go with #23 😄