fiberopenapi

Fiber OpenAPI

Fiber OpenAPI is an OpenAPI documentation generator for Fiber applications. It wraps Fiber’s router and provides methods to define OpenAPI specifications, security schemes, and serve a Swagger UI.

Features

• Define OpenAPI documentation for your Fiber routes.
• Support for security schemes, including API keys, HTTP Bearer authentication, and OAuth 2.0.
• Customizable OpenAPI configuration options.
• Seamless integration with Fiber’s routing system.
• Validate your OpenAPI configuration at startup.
• Leverage struct tags to generate OpenAPI schemas for request and response types.
• Serve OpenAPI JSON and an interactive Swagger UI out of the box.

Installation

Add the package to your Go project:

go get github.com/afkdevs/fiber-openapi

Usage

Create a new router, configure your OpenAPI settings, and define your routes. Below is a simple example:

package main

import (
	fiberopenapi "github.com/afkdevs/fiber-openapi"
	"github.com/afkdevs/fiber-openapi/option"
	"github.com/gofiber/fiber/v2"
)

func main() {
	app := fiber.New()
	r := fiberopenapi.NewRouter(app,
		fiberopenapi.WithTitle("My API"),
		fiberopenapi.WithVersion("1.0.0"),
		fiberopenapi.WithDescription("This is a sample API"),
		fiberopenapi.WithDocsPath("/docs"),
		fiberopenapi.WithServer("http://localhost:3000", "Local server"),
		fiberopenapi.WithSecurity("bearerAuth", fiberopenapi.SecurityHTTPBearer()),
	)

	api := r.Group("/api")
	v1 := api.Group("/v1")

	v1.Route("/auth", func(r fiberopenapi.Router) {
		r.Post("/login", dummyHandler).With(
			option.Summary("User Login"),
			option.Description("Endpoint for user login"),
			option.Request(new(LoginRequest)),
			option.Response(200, new(Response[Token])),
			option.Response(400, new(ErrorResponse)),
			option.Response(422, new(ValidationResponse)),
		)
		r.Get("/me", dummyHandler).With(
			option.Summary("Get User Profile"),
			option.Description("Endpoint to get the authenticated user's profile"),
			option.Security("bearerAuth"),
			option.Response(200, new(Response[UserProfile])),
			option.Response(401, new(ErrorResponse)),
		)
	}, option.WithRouteTags("Authentication"))

	v1.Route("/profile", func(r fiberopenapi.Router) {
		r.Put("/update", dummyHandler).With(
			option.Summary("Update User Profile"),
			option.Description("Endpoint to update the user's profile"),
			option.Request(new(UpdateProfileRequest)),
			option.Response(200, new(Response[UserProfile])),
			option.Response(400, new(ErrorResponse)),
			option.Response(422, new(ValidationResponse)),
		)
	}, option.WithRouteTags("Profile"), option.WithRouteSecurity("bearerAuth"))

	// Validate the OpenAPI configuration
	if err := r.Validate(); err != nil {
		panic(err)
	}

	app.Listen(":3000")
}

// Dummy handlers for demonstration purposes
func dummyHandler(c *fiber.Ctx) error {
	return c.SendString("Hello, World!")
}

type LoginRequest struct {
	Username   string `json:"username" example:"john_doe" validate:"required"`
	Password   string `json:"password" example:"password123" validate:"required"`
	RememberMe bool   `json:"remember_me" example:"true"`
}

type UpdateProfileRequest struct {
	Name     string `json:"name" example:"John Doe" validate:"required"`
	Email    string `json:"email" example:"john_doe@example.com" validate:"required,email"`
	Username string `json:"username" example:"john_doe" validate:"required"`
}

type Token struct {
	AccessToken  string `json:"access_token" example:"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."`
	RefreshToken string `json:"refresh_token" example:"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."`
}

type User struct {
	ID       string `json:"id" example:"12345"`
	Username string `json:"username" example:"john_doe"`
	Email    string `json:"email" example:"john_doe@example.com"`
	Name     string `json:"name" example:"John Doe"`
}

type Response[T any] struct {
	Status int `json:"status" example:"200"`
	Data   T   `json:"data,omitempty"`
}

type ErrorResponse struct {
	Status  int    `json:"status" example:"400"`
	Title   string `json:"title"`
	Detail  string `json:"detail"`
}

type ValidationResponse struct {
	Status int          `json:"status" example:"422"`
	Title  string       `json:"title" example:"Validation Error"`
	Detail string       `json:"detail" example:"Input data does not meet validation criteria"`
	Errors []FieldError `json:"errors" example:"[{\"field\":\"email\",\"message\":\"Email is required\"}]"`
}

type FieldError struct {
	Field   string `json:"field" example:"email"`
	Message string `json:"message" example:"Email is required"`
}

By default, your OpenAPI JSON and Swagger UI will be served at /docs.

More Examples

See the examples directory for more practical use cases.

Configuration Options

Global OpenAPI Options

• Title: API title.
• Version: API version.
• Description: API description.
• BaseURL: Base URL for your API (e.g., https://api.example.com).
• DocsPath: Path to serve OpenAPI docs and Swagger UI.
• Server: Define server URL and description.
• Security: Register security schemes like API keys or Bearer tokens.
• Swagger: Configure Swagger UI options.

Route Options (With)

• Summary: Short summary of the route.
• Description: Detailed description.
• Request: Request body schema.
• Response: Response schemas for status codes.
• Tags: Tags for grouping routes.
• Security: Route-specific security requirements.
• Deprecated: Mark route as deprecated.
• Hide: Exclude route from OpenAPI documentation.

Struct Tags

This package uses openapi-go for schema generation. Supported tags include:

• json: JSON field name.
• query: Query parameter name.
• path: Path parameter name.
• header: Header parameter name.
• formData: Form data parameter name.
• title: Custom title for the field.
• description: Description for the field.

For more details, see the openapi-go and jsonschema-go documentation.

License

This project is licensed under the MIT License. See the LICENSE file for details.