Tide: Generating Swagger from Tide

[brycefisher]

I'm a big fan of whats happening in Tide and the overall approach. Many web server frameworks in other languages allow for extensions that produce swagger output. The swagger output enables use of swagger tools which can codegen interactive documentation and clients in many popular programming languages.

While Tide is in an active design phase, I'm curious about the possibility of generating swagger output. Given the current thoughts on routes and extractors, would it be possible to generate swagger output from a server built atop Tide at compile time? Could this be accomplished as ergonomically as #[derive(Swagger)]? Would this have to a procedural macro?

I'd love to hear if swagger support is something Tide would like to someday support.

[tzilist]

I’d LOVE to have this. I think once we have a solid foundation for the framework we can begin working on quality of life things like swagger integration, codegen, etc. Easy swagger integration is on a long list of priorities for myself though. 😃

[brycefisher]

Awesome! I recognize this feature request is super early in the project lifecycle.

[bIgBV]

@tzilist I think it'd be a good idea to start collecting feature requests somewhere, right? That way once the 0.1 release is finalized, we can start looking at which features to pick up next. Plus, it would also give the community a good way to catch up on what's being worked on.

@aturon any thoughts?

[aturon]

@bIgBV I'm definitely in favor of keeping longer-term feature requests around. We can figure out a good labeling strategy to make clear what's going on.

[bIgBV]

@aturon We could probably use the project board as it ties in directly with issues and provides a very high level overview of what's going on in the project. Labels are a good idea, but the issue I find with that is that you can't get a high level overview of what's going on at a glance.

But, we will have to ask ourselves what do we want to communicate with the community.

[LiHRaM]

If someone is willing to help guide my efforts, I would like to work on this feature.

[pickfire]

@LiHRaM If possible, I would like to help you out as well but I don't have much time.

First, we would like to map out the possibilities to solve this? https://github.com/http-rs/tide/issues/101#issue-386525216

• generate swagger using doc comments but this would be ugly
• #[derive(Swagger)] but we probably need a generic one and would not want to solve the m-plus-n problem
  
  
  
  • it should best be like serde approach rather than golang tags since we may need one for OpenAPI v3 or Swagger v2 (it even confused me at first there there are 2 specs)
  
  
  • it should also fit into tide's vision (a rising tide lifts all boats), we could also take some inspiration from Python Social Auth or http-rs libraries on make it compatible with multiple framework
  
  
  • considering these, we could probably start another repository to experiment with this, but of course in the future other people could take ownership of it
  
  
  • I believe clap man page auto-generation would be a situation similar to us https://github.com/clap-rs/clap/issues/552
  
  
• one important one people may want is to have only compile-time cost, no run-time cost

Maybe we can just try discussing and prototyping some examples here to evaluate the different approaches.

Rocket have this issue as mentored for some time, maybe we could work together? https://github.com/SergioBenitez/Rocket/issues/297
Same goes for actix-web https://github.com/actix/actix-web/issues/310 (I actually prefer actix-web more for its performance)

[LiHRaM]

@pickfire Any help is welcome!

I like the idea of a framework-agnostic approach, and there are some existing approaches which we could draw inspiration from.
We're considering a framework to use for a university project, so I've compiled a list of alternatives which implement this currently:

• https://github.com/kdy1/rweb/blob/master/examples/openapi.rs
• https://paperclip.waffles.space/actix-plugin.html
• https://github.com/GREsau/okapi

I see there's already an openapi crate: https://github.com/softprops/openapi. They seem to support serialization and deserialization for both v2 and v3.0.1 of the spec.

Personally, I'm a fan of the rweb approach, i.e. deriving schemas from functions and then exposing a library function for constructing openapi documents from those.
Initially, we could try providing a macro which, using derive, allows us to generate openapi documents as found in the openapi crate?