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? #101 (comment)

• 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 Auto-generate manpage, help docs, etc. clap-rs/clap#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? rwf2/Rocket#297
Same goes for actix-web actix/actix-web#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?

[nicobao]

Hi!
Is it still on the roadmap?
Any existing solutions already out there?

[adriangb]

Hi folks! I'm just reading about Rust's web framework space, but for what it's worth, I really like the approach FastAPI used in the Python world: you declare your routes, query/path parameters and body using the type system (in the case of JSON bodies, there's an Extractor-like system), and you get OpenAPI for free! And OpenAPI descriptions are pulled from markdown formatted doctrings.

[songzhi]

@adriangb There's a framework rweb could do this, which is based on warp. But rweb seems not very popular. We still need this feature in popular web frameworks.

[dfseifert]

@adriangb I've been using FastAPI for quite some time now and i love it!
It uses Pydantic under the hood for models and just recently the author announced the Pydantic V2 Plan which includes a move from pure python to rust using PyO3 for bindings.

I myself am a total beginner in rust but maybe it is worth a look?