diff --git a/.github/workflows/lint.yaml b/.github/workflows/lint.yaml index dbe0a3e9..181f3f5d 100644 --- a/.github/workflows/lint.yaml +++ b/.github/workflows/lint.yaml @@ -3,6 +3,7 @@ name: Lint on: pull_request: push: + branches: ["main"] jobs: markdownlint: diff --git a/BENCHMARK.md b/BENCHMARK.md index c00af208..06edf67c 100644 --- a/BENCHMARK.md +++ b/BENCHMARK.md @@ -1,6 +1,7 @@ # Benchmark against other frameworks -We have benchmarked the API and the performance of Fuego against other popular frameworks. The results are shown below. +We have benchmarked the API and the performance of Fuego against other popular +frameworks. The results are shown below. ## API diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7be75d58..d778ad15 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,12 +1,16 @@ # Contributing -First of all, if you are reading this, thank you for considering contributing to the project! It's people like you that make it a reality. ❤️ +First of all, if you are reading this, thank you for considering contributing to + the project! It's people like you that make it a reality. ❤️ -In return, we will do our best to make the contribution process as easy and transparent as possible. +In return, we will do our best to make the contribution process as easy and +transparent as possible. ## How to contribute -There are many ways to contribute, from writing tutorials or blog posts, improving the documentation, submitting bug reports and feature requests or writing code which can be incorporated into the project itself. +There are many ways to contribute, from writing tutorials or blog posts, +improving the documentation, submitting bug reports and feature requests +or writing code which can be incorporated into the project itself. ## Installation @@ -20,4 +24,6 @@ There are many ways to contribute, from writing tutorials or blog posts, improvi ## Contributors -Thanks to [everyone who have contributed](https://github.com/go-fuego/fuego/graphs/contributors) to this project! +Thanks to [everyone who have contributed][contributors-url] to this project! + +[contributors-url]: https://github.com/go-fuego/fuego/graphs/contributors> diff --git a/Makefile b/Makefile index d86c4222..2b3d0e75 100644 --- a/Makefile +++ b/Makefile @@ -32,7 +32,6 @@ lint: lint-markdown: markdownlint --fix . - example: ( cd examples/full-app-gourmet && go run . -debug ) diff --git a/README.md b/README.md index 16e59fa6..75150313 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,4 @@ +

Fuego Logo

@@ -13,25 +14,42 @@ **Build your API or web application in minutes!** -Go framework generating OpenAPI documentation from code. Inspired by Nest, built for Go developers. +Go framework generating OpenAPI documentation from code. +Inspired by Nest, built for Go developers. -Also empowers `html/template`, `a-h/templ` and `maragudk/gomponents`: see [the example](./examples/full-app-gourmet) - actually running [in prod](https://gourmet.quimerch.com)! +Also empowers `html/template`, `a-h/templ` and `maragudk/gomponents`: +see [the example](./examples/full-app-gourmet) - actually running [in prod](https://gourmet.quimerch.com)! ## Why Fuego? -Chi, Gin, Fiber and Echo are great frameworks. But since they were designed a long time ago, [their current API does not allow them](https://github.com/gin-gonic/gin/issues/155) to deduce OpenAPI types from signatures, things that are now possible with generics. Fuego offers a lot of "modern Go based" features that make it easy to develop APIs and web applications. +Chi, Gin, Fiber and Echo are great frameworks. +But since they were designed a long time ago, +[their current API does not allow them][gin-gonic-issue] +to deduce OpenAPI types from signatures, things that are +now possible with generics. Fuego offers a lot of "modern Go based" +features that make it easy to develop APIs and web applications. ## Features -- **OpenAPI**: Fuego automatically generates OpenAPI documentation from **code** - _not from comments nor yaml files!_ -- **`net/http` compatible**: Fuego is built on top of `net/http`, so you can use any `http.Handler` middleware or handler! Fuego also supports `log/slog`, `context` and `html/template` +- **OpenAPI**: Fuego automatically generates OpenAPI documentation + from **code** - _not from comments nor yaml files!_ +- **`net/http` compatible**: Fuego is built on top of `net/http`, + so you can use any `http.Handler` middleware or handler! Fuego also supports + `log/slog`, `context` and `html/template` - **Routing**: Fuego provides a simple API for the Go 1.22 `net/http` -- **Serialization/Deserialization**: Fuego automatically serializes and deserializes JSON, XML and HTML Forms based on user-provided structs (or not, if you want to do it yourself) +- **Serialization/Deserialization**: Fuego automatically serializes and + deserializes JSON, XML and HTML Forms based on user-provided structs + (or not, if you want to do it yourself) - **Validation**: Fuego provides a simple and fast validator based on `go-playground/validator` -- **Transformation**: easily transform your data by implementing the `fuego.InTransform` and `fuego.OutTransform` interfaces - also useful for **validation** -- **Middlewares**: easily add a custom `net/http` middleware or use the provided middlewares. -- **Error handling**: Fuego provides centralized error handling with the standard [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457). -- **Rendering**: Fuego provides a simple and fast rendering system based on `html/template` - you can still also use your own template system like `templ` or `gomponents` +- **Transformation**: easily transform your data by implementing the + `fuego.InTransform` and `fuego.OutTransform` interfaces - also useful for **validation** +- **Middlewares**: easily add a custom `net/http` middleware + or use the provided middlewares. +- **Error handling**: Fuego provides centralized error handling with + the standard [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457). +- **Rendering**: Fuego provides a simple and fast rendering system based on + `html/template` - you can still also use your own template system like + `templ` or `gomponents` ## Examples @@ -121,7 +139,7 @@ func main() { fuego.Post(s, "/", myController). Description("This route does something"). Summary("This is my summary"). - Tags("MyTag"). // A tag is set by default according to the return type (can be desactivated) + Tags("MyTag"). // A tag is set by default according to the return type (can be deactivated) Deprecated() s.Run() @@ -245,12 +263,12 @@ curl http://localhost:8088 -X POST -d '{"name": "Fuego"}' -H 'Content-Type: appl ## From net/http to Fuego in 10s -https://github.com/go-fuego/fuego/assets/46993939/7438a71c-75a4-4e88-a584-71da6362c575 +
Views -#### Before +### Before image @@ -273,7 +291,8 @@ https://github.com/go-fuego/fuego/assets/46993939/7438a71c-75a4-4e88-a584-71da63 ## Contributing -See the [contributing guide](CONTRIBUTING.md). Thanks to [everyone who has contributed](https://github.com/go-fuego/fuego/graphs/contributors) to this project! ❤️ +See the [contributing guide](CONTRIBUTING.md). +Thanks to [everyone who has contributed][contributors-url] to this project! ❤️ ## Roadmap @@ -281,8 +300,14 @@ See the [board](https://github.com/orgs/go-fuego/projects/1). ## Disclaimer for experienced gophers -I know you might prefer to use `net/http` directly, but if having a frame can convince my company to use Go instead of Node, I'm happy to use it. +I know you might prefer to use `net/http` directly, +but if having a frame can convince my company to use +Go instead of Node, I'm happy to use it. ## License [MIT](./LICENSE.txt) + +[gin-gonic-issue]: https://github.com/gin-gonic/gin/issues/155 + +[contributors-url]: https://github.com/go-fuego/fuego/graphs/contributors diff --git a/documentation/README.md b/documentation/README.md index 022bcf57..a82d3186 100644 --- a/documentation/README.md +++ b/documentation/README.md @@ -1,41 +1,45 @@ # Website -This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator. +This website is built using [Docusaurus](https://docusaurus.io/), +a modern static website generator. ### Installation -``` -$ yarn +```sh +yarn ``` ### Local Development -``` -$ yarn dev +```sh +yarn dev ``` -This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. +This command starts a local development server and opens up a browser window. +Most changes are reflected live without having to restart the server. ### Build -``` -$ yarn build +```sh +yarn build ``` -This command generates static content into the `build` directory and can be served using any static contents hosting service. +This command generates static content into the `build` directory and +can be served using any static contents hosting service. ### Deployment Using SSH: -``` -$ USE_SSH=true yarn deploy +```sh +USE_SSH=true yarn deploy ``` Not using SSH: -``` -$ GIT_USER= yarn deploy +```sh +GIT_USER= yarn deploy ``` -If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch. +If you are using GitHub pages for hosting, this command is a convenient +way to build the website and push to the `gh-pages` branch. diff --git a/documentation/docs/guides/middlewares.md b/documentation/docs/guides/middlewares.md index 7693fa81..dc9b0316 100644 --- a/documentation/docs/guides/middlewares.md +++ b/documentation/docs/guides/middlewares.md @@ -2,9 +2,11 @@ Fuego supports `net/http` middlewares. -It means that all existing middlewares for `net/http`, including the ones from `chi` and `gorilla` can be used with Fuego! :fire: +It means that all existing middlewares for `net/http`, +including the ones from `chi` and `gorilla` can be used with Fuego! :fire: -You can use them to add functionalities to your routes, such as logging, authentication, etc. +You can use them to add functionalities to your routes, such as logging, +authentication, etc. ## App-level middlewares @@ -78,7 +80,8 @@ func main() { ## Route middlewares -You can also add middlewares to a single route. Simply add the middlewares as the last arguments of the route handler: +You can also add middlewares to a single route. +Simply add the middlewares as the last arguments of the route handler: ```go package main diff --git a/documentation/docs/guides/openapi.md b/documentation/docs/guides/openapi.md index f418033f..6ccf6838 100644 --- a/documentation/docs/guides/openapi.md +++ b/documentation/docs/guides/openapi.md @@ -26,7 +26,8 @@ Result for this simple example: ![Swagger UI](../../static/img/hello-world-openapi.png) -The core idea of Fuego is to generate the OpenAPI specification automatically, so you don't have to worry about it. However, you can customize it if you want. +The core idea of Fuego is to generate the OpenAPI specification automatically, +so you don't have to worry about it. However, you can customize it if you want. ## Operations @@ -66,7 +67,8 @@ Fuego automatically provides an OpenAPI specification for your API in several wa - **Swagger UI** - **JSON endpoint** -Fuego will indicate in a log the paths where the OpenAPI specifications and Swagger UI are available. +Fuego will indicate in a log the paths where the OpenAPI specifications and +Swagger UI are available. You can customize the paths and to activate or not the feature, with the option `WithOpenAPIConfig`. @@ -97,7 +99,8 @@ func main() { ## Custom UI -Fuego `Server` exposes a `UIHandler` field that enables you to implement your custom UI. +Fuego `Server` exposes a `UIHandler` field that enables you +to implement your custom UI. Example with http swagger: @@ -131,7 +134,8 @@ func main() { The default spec url reference Element Stoplight swagger ui. -Please note that if you embed swagger ui in your build it will increase its size by more than 10Mb. +Please note that if you embed swagger ui in your build it will increase its size +by more than 10Mb. | | StopLight Elements | Swagger | Disabled | | ------------- | ------------------ | -------------- | -------- | diff --git a/documentation/docs/guides/options.md b/documentation/docs/guides/options.md index 56031c6f..ca3c05be 100644 --- a/documentation/docs/guides/options.md +++ b/documentation/docs/guides/options.md @@ -51,7 +51,11 @@ s := fuego.NewServer( ### CORS -CORS middleware is not registered as a usual middleware, because it applies on routes that aren't registered. For example, `OPTIONS /foo` is not a registered route (only `GET /foo` is registered for example), but it's a request that needs to be handled by the CORS middleware. +CORS middleware is not registered as a usual middleware, +because it applies on routes that aren't registered. For example, +`OPTIONS /foo` is not a registered route +(only `GET /foo` is registered for example), +but it's a request that needs to be handled by the CORS middleware. ```go import "github.com/rs/cors" diff --git a/documentation/docs/index.md b/documentation/docs/index.md index 77c1e92c..544a6e11 100644 --- a/documentation/docs/index.md +++ b/documentation/docs/index.md @@ -22,4 +22,5 @@ Or **try Fuego immediately** by cloning **[one of our exemples](https://github.c ### What you'll need -- [Golang v1.22](https://golang.org/doc/go1.22) or above _(Fuego relies on a new feature of the net/http package only available after 1.22)_. +- [Golang v1.22](https://golang.org/doc/go1.22) or above +_(Fuego relies on a new feature of the net/http package only available after 1.22)_. diff --git a/documentation/docs/tutorials/01-hello-world.md b/documentation/docs/tutorials/01-hello-world.md index aed7bf7e..853b698a 100644 --- a/documentation/docs/tutorials/01-hello-world.md +++ b/documentation/docs/tutorials/01-hello-world.md @@ -4,13 +4,15 @@ Let's discover **Fuego** in a few lines. ## Quick start -If you don't want to copy/paste the code on your local setup, you can run the following command: +If you don't want to copy/paste the code on your local setup, you can run the +following command: ```bash go run github.com/go-fuego/fuego/examples/hello-world@latest ``` -Useful URLs (including OpenAPI spec & Swagger UI) are given in the terminal: you'll be able to see the result in your browser. +Useful URLs (including OpenAPI spec & Swagger UI) are given in the terminal: +you'll be able to see the result in your browser. ## Start from scratch diff --git a/documentation/docs/tutorials/02-crud.md b/documentation/docs/tutorials/02-crud.md index 9cc162c2..7ce1544f 100644 --- a/documentation/docs/tutorials/02-crud.md +++ b/documentation/docs/tutorials/02-crud.md @@ -14,7 +14,8 @@ fuego controller books go run github.com/go-fuego/fuego/cmd/fuego@latest controller books ``` -After executing the above code, you need to slightly modify the generated controllers/books.go and main.go files. +After executing the above code, +you need to slightly modify the generated controllers/books.go and main.go files. ```go title="controllers/books.go" {8-9,28-39} package controller @@ -95,7 +96,8 @@ The generator will create the following routes: :::tip -Fuego comes with a [**generator**](#generation) that can generates CRUD routes and controllers for you! +Fuego comes with a [**generator**](#generation) +that can generates CRUD routes and controllers for you! ::: diff --git a/documentation/docs/tutorials/03-hot-reload.md b/documentation/docs/tutorials/03-hot-reload.md index 2a229d27..67df9bbd 100644 --- a/documentation/docs/tutorials/03-hot-reload.md +++ b/documentation/docs/tutorials/03-hot-reload.md @@ -1,6 +1,9 @@ # Hot reload -Hot reload is a feature that allows you to update your code and see the changes in real-time without restarting the server. This is very useful for development, as it allows you to see the changes you make to your code immediately. +Hot reload is a feature that allows you to update your code and +see the changes in real-time without restarting the server. +This is very useful for development, +as it allows you to see the changes you make to your code immediately. To enable hot reload, you need to install the `air` command-line tool: diff --git a/documentation/docs/tutorials/rendering/gomponents.md b/documentation/docs/tutorials/rendering/gomponents.md index 4e338813..5b104c69 100644 --- a/documentation/docs/tutorials/rendering/gomponents.md +++ b/documentation/docs/tutorials/rendering/gomponents.md @@ -2,7 +2,8 @@ Fuego supports rendering HTML templates with [Gomponents](https://github.com/maragudk/gomponents). -Just use the `fuego.Gomponent` type as a return type for your handler, and return the gomponent. +Just use the `fuego.Gomponent` type as a return type for your handler, +and return the gomponent. ```go // highlight-next-line @@ -29,4 +30,6 @@ func (rs Ressource) adminIngredients(c fuego.ContextNoBody) (fuego.Gomponent, er } ``` -Note that the `fuego.Gomponent` type is a simple alias for `fuego.Renderer` : any type that implements the `Render(io.Writer) error` method can be used as a return type for a handler. +Note that the `fuego.Gomponent` type is a simple alias for `fuego.Renderer`: +any type that implements the `Render(io.Writer) error` +method can be used as a return type for a handler. diff --git a/documentation/docs/tutorials/rendering/index.md b/documentation/docs/tutorials/rendering/index.md index b039a14f..9e7dd2a1 100644 --- a/documentation/docs/tutorials/rendering/index.md +++ b/documentation/docs/tutorials/rendering/index.md @@ -2,4 +2,5 @@ Fuego is not only capable to handle XML and JSON, it can also render HTML. -It supports templating with [html/template](https://pkg.go.dev/html/template), [Templ](https://github.com/a-h/templ), and [Gomponents](https://github.com/maragudk/gomponents). +It supports templating with [html/template](https://pkg.go.dev/html/template), +[Templ](https://github.com/a-h/templ), and [Gomponents](https://github.com/maragudk/gomponents). diff --git a/documentation/docs/tutorials/rendering/std.md b/documentation/docs/tutorials/rendering/std.md index 7f1c4aea..ee5431f8 100644 --- a/documentation/docs/tutorials/rendering/std.md +++ b/documentation/docs/tutorials/rendering/std.md @@ -4,9 +4,11 @@ sidebar_position: 1 # html/template -Fuego supports rendering HTML templates with the [html/template](https://pkg.go.dev/html/template) package. +Fuego supports rendering HTML templates with the +[html/template](https://pkg.go.dev/html/template) package. -Just use the `fuego.HTML` type as a return type for your handler, and return `c.Render()` with the template name and data. +Just use the `fuego.HTML` type as a return type for your handler, and return +`c.Render()` with the template name and data. ```go // highlight-next-line diff --git a/documentation/docs/tutorials/rendering/templ.md b/documentation/docs/tutorials/rendering/templ.md index 8dfcaea3..3d3e2bf4 100644 --- a/documentation/docs/tutorials/rendering/templ.md +++ b/documentation/docs/tutorials/rendering/templ.md @@ -2,7 +2,8 @@ Fuego supports templating with [Templ](https://github.com/a-h/templ). -Simply return a Templ component from your handler, with the `fuego.Templ` return type. +Simply return a Templ component from your handler, +with the `fuego.Templ` return type. Example from [a recipe app](https://github.com/go-fuego/fuego/tree/main/examples/full-app-gourmet): @@ -31,4 +32,6 @@ func (rs Ressource) adminIngredients(c fuego.ContextNoBody) (fuego.Templ, error) } ``` -Note that the `fuego.Templ` type is a simple alias for `fuego.CtxRenderer` : any type that implements the `Render(context.Context, io.Writer) error` method can be used as a return type for a handler. +Note that the `fuego.Templ` type is a simple alias for `fuego.CtxRenderer`: +any type that implements the `Render(context.Context, io.Writer) error` +method can be used as a return type for a handler. diff --git a/documentation/src/pages/markdown-page.md b/documentation/src/pages/markdown-page.md index 9756c5b6..7f7d2fd1 100644 --- a/documentation/src/pages/markdown-page.md +++ b/documentation/src/pages/markdown-page.md @@ -1,7 +1,3 @@ ---- -title: Markdown page example ---- - # Markdown page example You don't need React to write simple standalone pages.