search

swagger-api / swagger-codegen

swagger-codegen contains a template-driven engine to generate documentation, API clients and server stubs in different languages by parsing your OpenAPI / Swagger definition.
http://swagger.io
Apache License 2.0
17.05k stars 6.03k forks source link

[Rust, Rust-server] should we merge the two rust generators into one? #7347

Open bjgill opened 6 years ago

bjgill commented 6 years ago

Description

I'm currently seeing a lot of PRs for rust seeking to add features that rust-server already has. It's going to be rather tedious to keep maintaining two parallel Rust generators.

Suggest a fix/enhancement

It would surely be more efficient to either pick only one for future maintenance or merge the two?

bjgill commented 6 years ago

@frol @farcaller @wing328 - I don't know if you have any views on this? I don't know rust very well, so don't actually know if it has any features lacking from rust-server or vice-versa...

frol commented 6 years ago

I am not the right person to ask this. I have not done anything but reviews of PRs to the Rust generators (I mean, I won't be able to implement any of the two generators myself in Rust), so I cannot make any decision here. I agree that a single implementation would be easier to maintain, so if someone is willing to make that move, that would be great!

aykutakin commented 6 years ago

I see the benefit of merging this two implementations (having one source of truth, increasing maintainability, no need to patch 2 different place etc.). However, what should people do that only need client code in case of these implementations are merged? Should they generate code and remove server code later? Exact opposite is also valid if they only need server code.

As far as I see from other languages, client and server codes are generated separately. So, it may make sense to extract client code from rust-server completely and continue with separate implementations.

Please let me know if you have different kind of concerns about separating 2 implementations without leaving dependencies between them

farcaller commented 6 years ago

Theoretically, we can hide the server code behind a cfg gate.

wing328 commented 6 years ago

Based on my experiences with other generators, I would suggest:

The consolidation does not imply which Rust client (rust or rust-server's client code) is better.

The goal is to consolidate all efforts into one Rust client generator so that all Rust developers are better off maintaining just one generator for Rust client.

Ref: https://github.com/swagger-api/swagger-codegen/issues/6756

aykutakin commented 6 years ago

Well, I can take over this issue, however I think it'd make sense to wait hyper version upgrade to deal with less complications

wing328 commented 6 years ago

Well, I can take over this issue, however I think it'd make sense to wait hyper version upgrade to deal with less complications

Agreed 👍

bjgill commented 6 years ago

A few comments based on my knowledge of the design of rust_server:

I see the benefit of merging this two implementations (having one source of truth, increasing maintainability, no need to patch 2 different place etc.). However, what should people do that only need client code in case of these implementations are merged? Should they generate code and remove server code later? Exact opposite is also valid if they only need server code.

Currently, rust-server has client and server features. This allows users to omit whichever one they don't need. The unused code will still be in the autogenerated output, but will be ignored by the Rust compiler when the appropriate feature is specified.

As far as I see from other languages, client and server codes are generated separately. So, it may make sense to extract client code from rust-server completely and continue with separate implementations.

Please let me know if you have different kind of concerns about separating 2 implementations without leaving dependencies between them

When creating rust-server, it was a deliberate design decision to have the client and server closely tied together. Clients use the same trait that servers implement. This means that you can effectively create a distributed strongly typed system - the Rust compiler can verify that there are no mis-matches between servers and clients. This unification also means that we can safely pass around a Context object, which allows us to include a trail ID with the logs we generate.

rust-server is therefore quite different to most of the generators for other languages. My impression is that the other generators have been created by people interested in either servers or clients. rust-server, by contrast, is designed for systems containing a mix of both servers and clients.

wing328 commented 6 years ago

This allows users to omit whichever one they don't need. The unused code will still be in the autogenerated output, but will be ignored by the Rust compiler when the appropriate feature is specified.

Another option is to leverage the .swagger-codegen-ignore file to skip generating files for client or server if the user only needs either one of them.

My impression is that the other generators have been created by people interested in either servers or clients. rust-server, by contrast, is designed for systems containing a mix of both servers and clients.

haskell (servant) generator is another example that generates both server and client. Similarly, there's a Haskell client generator (haskell-http-client) to focus just on the client generation for Haskell developers.