openapi

OpenAPI

Automatic OpenAPI 3.0.4 and 3.1.2 specification generation for Go applications.

📚 Complete Documentation →

Documentation

This README provides a quick overview. For comprehensive guides, tutorials, and API reference:

• Installation Guide - Get started
• User Guide - Learn the features
• API Reference - Complete API docs
• Examples - Real-world patterns
• Troubleshooting - FAQs and solutions

Features

• Clean API - API.Spec(ctx) and API.AddOperation(); operations from WithOperations or added incrementally
• Type-Safe Version Selection - V30x and V31x constants
• Operation Builders - WithGET(), WithPOST(), WithPUT(), etc.
• Automatic Parameter Discovery - Extracts parameters from struct tags
• Schema Generation - Converts Go types to OpenAPI schemas
• Swagger UI Configuration - Built-in, customizable UI
• Type-Safe Diagnostics - diag package for warning control
• Built-in Validation - Validates against official meta-schemas

Installation

go get rivaas.dev/openapi

Requires Go 1.25+

Quick Start

package main

import (
    "context"
    "fmt"
    "log"

    "rivaas.dev/openapi"
)

type User struct {
    ID    int    `json:"id"`
    Name  string `json:"name"`
    Email string `json:"email"`
}

type CreateUserRequest struct {
    Name  string `json:"name" validate:"required"`
    Email string `json:"email" validate:"required,email"`
}

func main() {
    api := openapi.MustNew(
        openapi.WithTitle("My API", "1.0.0"),
        openapi.WithDescription("API for managing users"),
        openapi.WithServer("http://localhost:8080", "Local development"),
        openapi.WithBearerAuth("bearerAuth", "JWT authentication"),
    )
    getOp, _ := openapi.WithGET("/users/:id", openapi.WithSummary("Get user"), openapi.WithResponse(200, User{}), openapi.WithSecurity("bearerAuth"))
    postOp, _ := openapi.WithPOST("/users", openapi.WithSummary("Create user"), openapi.WithRequest(CreateUserRequest{}), openapi.WithResponse(201, User{}))
    delOp, _ := openapi.WithDELETE("/users/:id", openapi.WithSummary("Delete user"), openapi.WithResponse(204, nil), openapi.WithSecurity("bearerAuth"))
    if err := api.AddOperation(getOp, postOp, delOp); err != nil {
        log.Fatal(err)
    }

    result, err := api.Spec(context.Background())
    if err != nil {
        log.Fatal(err)
    }

    // Check for warnings (optional)
    if len(result.Warnings) > 0 {
        fmt.Printf("Generated with %d warnings\n", len(result.Warnings))
    }

    fmt.Println(string(result.JSON))
}

See more examples →

Learn More

• Basic Usage - Generate your first spec
• Configuration - API settings and version selection
• Security - Authentication schemes
• Operations - Define HTTP endpoints
• Auto-Discovery - Struct tag reference
• Swagger UI - Customize the UI

Contributing

Contributions are welcome! Please see the main repository for contribution guidelines.

License

Apache License 2.0 - see LICENSE for details.

---

Part of the Rivaas web framework ecosystem.