From 3395ada1efe411b10b9f7756a9df192bc110a248 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arist=C3=B3teles=20Coutinho?= Date: Tue, 19 Dec 2023 11:04:17 -0300 Subject: [PATCH] docs: add basic guides to usage lennarb --- guides/getting-started/readme.md | 47 ++++++++++++ guides/middlewares/readme.md | 121 ++++++++++++++++++++++++++++++ guides/namespace-routes/readme.md | 76 +++++++++++++++++++ 3 files changed, 244 insertions(+) create mode 100644 guides/getting-started/readme.md create mode 100644 guides/middlewares/readme.md create mode 100644 guides/namespace-routes/readme.md diff --git a/guides/getting-started/readme.md b/guides/getting-started/readme.md new file mode 100644 index 0000000..853d15f --- /dev/null +++ b/guides/getting-started/readme.md @@ -0,0 +1,47 @@ +# Getting Started + +This guide show you how to use the `lennarb` + +## Instalation + +Add the gem to your project: + +```bash +$ gem add lennarb +``` + +## Usage + +To use the gem, you need to require and use `Lenna::Application` or `Leann::Base` to define your routes: + +```ruby +# config.ru + +require 'lennarb' + +app = Lenna::Application.new do |route| + route.get '/' do |req, res| + res.html 'Hello World' + end +end + +run app +``` + +Done! Now you can run your app: + +```bash +$ rackup + +Puma starting in single mode... +* Puma version: 6.4.0 (ruby 3.2.2-p53) ("The Eagle of Durango") +* Min threads: 0 +* Max threads: 5 +* Environment: development +* PID: 94360 +* Listening on http://127.0.0.1:9292 +* Listening on http://[::1]:9292 +Use Ctrl-C to stop +^C- Gracefully stopping, waiting for requests to finish +=== puma shutdown: 2023-12-19 08:54:26 -0300 === +``` diff --git a/guides/middlewares/readme.md b/guides/middlewares/readme.md new file mode 100644 index 0000000..2d549c8 --- /dev/null +++ b/guides/middlewares/readme.md @@ -0,0 +1,121 @@ +# Middlewares + +Middlewares are functions that are executed before the request handler. They are useful for tasks such as authentication, authorization, logging, etc. + +The Lenna use two default middlewares: `Lenna::Middleware::ErrorHandler` and `Lenna::Middleware::Logging` + +- `Lenna::Middleware::ErrorHandler` is responsible for handling errors and returning a response with the error message. + +- `Lenna::Middleware::Logging` is responsible for logging the request and response. + +## Creating a middleware + +To create a middleware, you can use some object that responds to `#call` and receives `req`, `res` and `next_middleware` as arguments. + +```ruby +# my_middleware.rb + +class MyMiddleware + def call(req, res, next_middleware) + # Do something + next_middleware.call + end +end +``` + +The next middleware is a function that calls the next middleware in the chain. If there is no next middleware, it calls the request handler. + +You can use a lambda to create a middleware: + +```ruby + +my_middleware = -> (req, res, next_middleware) { + # Do something + next_middleware.call +} +``` + +## Using a middleware + +To use a middleware, you need to use `Lenna::Application#use`: + +```ruby +# my_app.rb + +require 'lennarb' + +Lenna::Application.new do |route| + route.get '/' do |req, res| + res.html 'Hello World' + end + + route.use(MyMiddleware) +end +``` + +Now, the `MyMiddleware` will be executed before the request handler. + +## Using multiple middlewares + +You can use multiple middlewares: + +```ruby +# my_app.rb + +require 'lennarb' + +Lenna::Application.new do |route| + route.get '/' do |req, res| + res.html 'Hello World' + end + + route.use([MyMiddleware, AnotherMiddleware]) +end +``` + +Now, the `MyMiddleware` and `AnotherMiddleware` will be executed before the request handler. + +## Using middlewares in a specific route + +You can use middlewares in a specific route: + +```ruby +# my_app.rb + +require 'lennarb' + +Lenna::Application.new do |route| + route.get '/' do |req, res| + res.html 'Hello World' + end + + route.get '/users', MyMiddleware do |req, res| + res.html 'Users' + end +end +``` + +Now, the `MyMiddleware` will be executed before the request handler of `/users` route. + +## Using middlewares in a specific namespace + +You can use middlewares in a specific namespace: + +```ruby + +# my_app.rb + +require 'lennarb' + +Lenna::Application.new do |route| + route.get '/' do |req, res| + res.html 'Hello World' + end + + route.namespace '/api', MyMiddleware do |api| + api.get '/users' do |req, res| + res.json [{ name: 'John' }, { name: 'Doe' }] + end + end +end +``` diff --git a/guides/namespace-routes/readme.md b/guides/namespace-routes/readme.md new file mode 100644 index 0000000..ae75c0c --- /dev/null +++ b/guides/namespace-routes/readme.md @@ -0,0 +1,76 @@ +# Namespace routes + +This guide show you how to use namespace routes. + +## Usage + +To use namespace routes, you need to use `Lenna::Application#namespace`: + +```ruby +# my_app.rb + +require 'lennarb' + +Lenna::Application.new do |route| + route.namespace '/api' do |api| + api.get '/users' do |req, res| + res.json [{ name: 'John' }, { name: 'Doe' }] + end + end +end +``` + +Now, you have a route `/api/users` that returns a JSON with users. + +```bash +$ curl http://localhost:9292/api/users + +[{"name":"John"},{"name":"Doe"}] +``` + +## Nested namespaces + +You also can use nested namespaces: + +```ruby +# my_app.rb + +require 'lennarb' + +Lenna::Application.new do |route| + route.namespace '/api' do |api| + api.namespace '/v1' do |v1| + v1.get '/users' do |req, res| + res.json [{ name: 'John' }, { name: 'Doe' }] + end + end + api.namespace '/v2' do |v2| + v2.get '/users' do |req, res| + res.json [{ name: 'John' }, { name: 'Doe' }] + end + end + end +end +``` + +Now, you have a route `/api/v1/users` that returns a JSON with users. + +```bash +$ curl http://localhost:9292/api/v1/users + +[{"name":"John"},{"name":"Doe"}] +``` + +And a route `/api/v2/users` that returns a JSON with users. + +```bash +$ curl http://localhost:9292/api/v2/users + +[{"name":"John"},{"name":"Doe"}] +``` + +## Middlewares + +The next version of Lenna will support middlewares in namespaces. For now, you can use `Lenna::Application#use`: + +Done! Now you can use namespace routes in your app.