OpenAPIv3 support to define routes, endpoints and stubs

[brainstorm]

Hello @softprops,

Thanks for pushing this crate out, it was a breeze to get started with Rust+API Gateway+Http lambdas thanks to you 👍

Now, before I dive into defining my endpoints right into main.rs, abstact it away, and iterate as usual, I would like to have some code scaffolding first. I would like to first know if you have some insight into putting OpenAPI (Swagger) specs to work with this serverless crate and/or lando?

My original idea was to generate code given a particular OpenAPI spec, but the resulting code is quite... overwhelming and boilerplate-y as a starting point, imho:

https://github.com/brainstorm/htsget-rust

Instead, I'm trying to start small while having the API Gateway code scaffold and Lambda handler(s) stubs in place, right now just your README.md scaffold really:

https://github.com/brainstorm/htsget-aws

Putting aside the whole code generation stuff for OpenAPI, how would you tackle this for starters?

For instance, would you include Rust's Rocket crate to start? Or perhaps just go for plain tokio+http?

Would you define the endpoints in serverless.yml, create a single lambda per endpoint and go from there or another strategy?

Just getting my feet wet with all this and wanted to have some good starting pointers from the pros ;)

/cc @chris-zen @delagoya

[softprops]

@brainstorm thanks for reaching out.

That's a bit out of scope for that this repo represents.

This repository exists as a vanilla serverless create template targeting a basic "hello world" example for getting started with the serverless rust plugin.

I do like your idea though. You may want to take a look at tooling that already exists in this space. swagger codegen is an established and extensible tool that takes a template and an openapi specification and generates code. You may actually want to start there. The templates themselves aren't specific to a framework but rather anything you'd possible want to generate from an openapi schema file.

I think it would be very interesting to implement a swagger codegen module for rust and serverless framework. It's not on my roadmap but if it existed, I would definitely consider giving it a look!

Specifically in the aws lambda space I know there is tooling that exists for providing an openapi schema to apigateway to provision a set of routes. I haven't looked too closely but I'd be interesting in exploring it.

This project's primary focus is mainly to bring a more seamless serverless framework experience to rust applications. There's a pretty big serverless framework ecosystem that this gets to place nice with for free as a result. There may also be some serverless framework tooling specific tool that enables what you're looking for. I'm not immediately aware of one though

[brainstorm]

Thanks @softprops for the feedback, I understand.

Indeed, I looked at modifying the OpenAPI3 codegen (same as swagger-codegen) "mustache" templates to potentially have generated code that directly integrates with your neat serverless-aws-rust-http code (via the .yaml spec I wrote as input).

But first I wanted to have an example (complete?) multi-endpoint project right after using this repo template to have as a reference.

TL;DR: I wanted to see how you structured a "real world" project you bootstrapped from this repo, since I definitely want to use it as my base. If that's not available, I will go ahead full steam and "go my own way" ;)

Makes sense? Thanks for your time and valuable insights!

[softprops]

I wanted to see how you structured a "real world" project you bootstrapped from this repo,

I think I can commit to another example repo.

Aside: I've found the default templating provided by serverless create limiting. I'm working on some a more flexible alternative but it's not likely to be openapi based. I'd love to be kept up to date with what youre working on. It sounds super interesting!

[brainstorm]

That example repo would be great to see, thank you!

I'll be developing over here for now:

https://github.com/brainstorm/htsget-aws

I went for the following endpoints in serverless.yml, one .zip/lambda per endpoint:

functions:
  reads:
    # handler value syntax is `{cargo-package-name}.{bin-name}`
    # or `{cargo-package-name}` for short when you are building a
    # default bin for a given package.
    handler: htsget.reads
    events:
      - http:
          path: '/reads'
          method: GET
  variants:
    handler: htsget.variants
    events:
      - http:
          path: '/variants'
          method: GET

But as I mentioned I would have been rad if that section was populated by and compliant with OpenAPI3 htsget spec I wrote beforehand.

In any case, I'll keep you posted and thanks again for your support and patience 👍