Skip to main content

OpenAPI Documentation

Github StackBlitz

This project demonstrates how to add OpenAPI 3 documentation to a Go application using Huma.

This project got inspired by the swagger recipe.

Prerequisites​

Ensure you have the following installed:

  • Golang

Setup​

  1. Clone the repository:

    git clone https://github.com/gofiber/recipes.git
    cd recipes/openapi

  2. Download Go modules:

    go mod tidy

Running the Application​

  1. Start the application:

    go run main.go

  2. Access the API Documentation: Open your browser and navigate to http://localhost:3000/docs.

  3. OpenAPI Specs:

    • OpenAPI 3.1 JSON: http://localhost:3000/openapi.json.
    • OpenAPI 3.1 YAML: http://localhost:3000/openapi.yaml.
    • OpenAPI 3.0.3 JSON: http://localhost:3000/openapi-3.0.json.
    • OpenAPI 3.0.3 YAML: http://localhost:3000/openapi-3.0.yaml.

  4. Generating TypeScript schema:

    npx openapi-typescript http://localhost:3000/openapi.json -o schema.ts

Example​

Here is a minimal example of adding huma to a existing Fiber codebase:

routes.go​

import (
   ...
   "github.com/gofiber/fiber/v2"
   "github.com/danielgtaylor/huma/v2"
   "github.com/danielgtaylor/huma/v2/adapters/humafiber"
)
func New() *fiber.App {
   app := fiber.New()
   api := humafiber.New(app, huma.DefaultConfig("Book API", "1.0.0"))

   // app.Get("/books", handlers.GetAllBooks) // 👈 your existing code
   huma.Get(api, "/books", handlers.GetAllBooks) // 👈 huma version
   return app
}

handlers/book.go​

// func GetAllBooks(c *fiber.Ctx) error {} // 👈 your existing code

// 👇 huma version
func GetAllBooks(ctx context.Context, _ *struct{}) (*GetAllBooksResponse, error) {
   return &GetAllBooksResponse{Body: books}, nil
}

Enhancing Documentation​

You can use huma.Register to add more information to the OpenAPI specification, such as descriptions with Markdown, examples, tags, and more.

// huma.Get(group, "/books/{id}", handlers.GetBookByID)

huma.Register(api, huma.Operation{
   OperationID: "get-book-by-id",
   Method:      http.MethodGet,
   Path:        "/book/{id}",
   Summary:     "Get a book",
   Description: "Get a book by book ID.",
   Tags:        []string{"Books"},
}, handlers.GetBookByID)

References​