openapi_description.go

package fuego

const openapiDescription = `
This is the autogenerated OpenAPI documentation for your [Fuego](https://github.com/go-fuego/fuego) API.

Below is a Fuego Cheatsheet to help you get started. Don't hesitate to check the [Fuego documentation](https://go-fuego.github.io/fuego) for more details.

Happy coding! 🔥

## Usage

### Route registration

` + "```go" + `
func main() {
	// Create a new server
	s := fuego.NewServer()

	// Register some routes
	fuego.Post(s, "/hello", myController)
	fuego.Get(s, "/myPath", otherController)
	fuego.Put(s, "/hello", thirdController)

	adminRoutes := fuego.Group(s, "/admin")
	fuego.Use(adminRoutes, myMiddleware) // This middleware (for authentication, etc...) will be available for routes starting by /admin/*, 
	fuego.Get(adminRoutes, "/hello", groupController) // This route will be available at /admin/hello

	// Start the server
	s.Start()
}
` + "```" + `

### Basic controller

` + "```go" + `
type MyBody struct {
	Name string ` + "`json:\"name\" validate:\"required,max=30\"`" + `
}

type MyResponse struct {
	Answer string ` + "`json:\"answer\"`" + `
}

func hello(ctx fuego.ContextWithBody[MyBody]) (*MyResponse, error) {
	body, err := ctx.Body()
	if err != nil {
		return nil, err
	}

	return &MyResponse{Answer: "Hello " + body.Name}, nil
}
` + "```" + `

### Add openAPI information to the route

` + "```go" + `
import (
	"github.com/go-fuego/fuego"
	"github.com/go-fuego/fuego/option"
	"github.com/go-fuego/fuego/param"
)

func main() {
	s := fuego.NewServer()

	// Custom OpenAPI options
	fuego.Post(s, "/", myController
		option.Description("This route does something..."),
		option.Summary("This is my summary"),
		option.Tags("MyTag"), // A tag is set by default according to the return type (can be deactivated)
		option.Deprecated(), // Marks the route as deprecated in the OpenAPI spec

		option.Query("name", "Declares a query parameter with default value", param.Default("Carmack")),
		option.Header("Authorization", "Bearer token", param.Required()),
		optionPagination,
		optionCustomBehavior,
	)

	s.Run()
}

var optionPagination = option.Group(
	option.QueryInt("page", "Page number", param.Default(1), param.Example("1st page", 1), param.Example("42nd page", 42)),
	option.QueryInt("perPage", "Number of items per page"),
)

var optionCustomBehavior = func(r *fuego.BaseRoute) {
	r.XXX = "YYY"
}
` + "```" + `

Then, in the controller

` + "```go" + `
type MyResponse struct {
	Answer string ` + "`json:\"answer\"`" + `
}

func getAllPets(ctx fuego.ContextNoBody) (*MyResponse, error) {
	name := ctx.QueryParam("name")
	perPage, _ := ctx.QueryParamIntErr("per_page")

	return &MyResponse{Answer: "Hello " + name}, nil
}
` + "```" + `
`