The Crystal Programming Language Forum

Ricr: simple web framework/router with Swagger support

Hello there,
I have been actively working on a new web framework (another one you can say): ricr.

Here are the unique features:

  • Swagger/OpenAPI support!
  • type safety, as most as possible (also helps api docs generation)
  • modular – e.g. putting several routes behind authentication is very easy
  • yet simple by avoiding boilerplates with Controllers

I would like to gather your feadbacks here:

  • any existing point to change
  • any new lacking feature you wish (e.g. websockets, possible responses in swagger docs)
  • are “the selling points” big enough to have enough traction to make this new project living?

Project URL -> https://github.com/ricr-web/ricr
Edit: the new project lives in https://github.com/grip-framework/gripen

Thank you!

5 Likes

Extremely important question: how do you pronounce “Ricr”?

Ricer, like the tool :smile:

1 Like

Generating a OpenAPI json is good, it would be even better to have a way to declare a special route that serves the swagger-ui!

as in “Rice”

or as in Enterprise Number One Riker?

1 Like

I thought “richer” :rofl:

1 Like

Ali Naqvi sent a very interesting idea: make initial code boilerplate from a OpenAPI JSON.

Ballerina lang does it.
It is a good way to help adoption from existing projects.

I forgot previously to mention, as a major feature compared to Kemal and others, there is a route conflict detection. An error will be raised at startup if there on any conflict.

I just added Swagger API documentation page support, all we need is:

require "ricr"
require "ricr/docs"

ricr = Ricr.new
ricr.controller.docs_route
ricr.start

Now a API docs page is served at http://localhost:3000/docs!

1 Like

If you want swagger as a unique selling point, creating yet another DSL on top of swagger format feels useless if I say my opinion. This is what I would like to have when I hear “openapi support”: let me create my type definitions with Array, Hashes and basic types and set them the type for the body and the response. Then have your framework generate the swagger spec for me based on those. I don’t want to write type definitions in two places.

Here’s an example in python:

1 Like

There is only one place, the code. From it, the swagger docs are generated.
Request and response body are objects defined in the code.
Not sure to understand?

For now request_body is implemented, but not possible responses on the OpenAPI docs.

It is error-prone to have to set the possible responses in an array, the route can return totally different things than thought.
As I see, they will be generated from the route return types.

For instance, a given route get /user returns User | UserNotFound (its Proc return types). Both this types will have annotations for the error code, description, examples.

This is what I meant. The schema of a post body as well as the one of the response should be derived by the route input and return types respectively. If you want to document errors, use Unions. And possibly allow for manually having return types that span accross all routes manually, for example errors.

1 Like

Ok, so nothing wrong with the actual implementation, but things missing.

Errors are a bit special – I think it will have to be like any return type, like User | InvalidUserError.
Otherwise there is no way to tell possible errors.

For parameters errors, same concept: returning an exception, or there will be a default one.

No one can pronounce “ricr” when they first saw it. You should make your project name more readable first.

1 Like

Maybe, I wanted to have the cr at the end to point out it is made in Crystal, and a funny name.
Not sure it is a big deal if we mispronounce it.

1 Like

Hello everyone, I’m glad to announce you the merge of the project with Grip.
The process is still ongoing, then new repository lives here: https://github.com/grip-framework/gripen.

The main goal is to combine our efforts to make a better web framework, having both Swagger docs from Ricr and user-friendliness from Grip.

4 Likes