Skip to content

README.md

Latest commit

 

History

History
146 lines (110 loc) · 5.11 KB

README.md

File metadata and controls

146 lines (110 loc) · 5.11 KB
Go OpenAPI Validator Logo

Go OpenAPI Validator

A framework-agnostic OpenAPI v3 validator for Go, designed for performance and reliability.

Go Version License OpenAPI Version
Tests Status Coverage
Security Policy Code of Conduct PRs Welcome

📖 Overview

Go OpenAPI Validator is a high-performance, framework-agnostic library for validating HTTP requests and responses against OpenAPI v3 specifications. Inspired by express-openapi-validator, it provides a robust middleware layer that ensures your API remains consistent with its documentation.

We focus on minimalism and reliability, with zero external testing dependencies and a lean footprint.

✨ Key Features

  • 🚀 Framework Agnostic: Native support for net/http, Gorilla Mux, and Gin.
  • 🛡️ Request Validation: Automatic validation of request bodies, query parameters, and headers.
  • ✅ Response Validation: Optional outgoing response validation to catch implementation errors.
  • 📄 Swagger UI: Built-in, zero-config Swagger UI integration served at /docs.
  • 🧪 Professional Grade: Comprehensive test suite using only the Go standard library.
  • ⚙️ Highly Configurable: Custom error encoders, router selection, and more.

🛠️ System Requirements

Before you begin, ensure you have the following installed:

  • Go: v1.21.x or higher (Tested with v1.23+)
  • Git: For version control

🚀 Getting Started

1. Installation

go get github.com/vihuvac/go-openapi-validator

2. Usage Examples

Standard Library (net/http)

package main

import (
	"log"
	"net/http"
	"github.com/getkin/kin-openapi/routers/legacy"
	validator "github.com/vihuvac/go-openapi-validator"
)

func main() {
	v, err := validator.New("openapi.yaml")
	if err != nil {
		log.Fatal(err)
	}

	// For net/http, use the legacy router
	r, _ := legacy.NewRouter(v.Swagger)
	validator.WithRouter(r)(v.Options)

	mux := http.NewServeMux()
	v.HandleSwaggerUI(mux)

	mux.HandleFunc("/hello", func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("Content-Type", "application/json")
		w.Write([]byte(`{"message": "Hello World"}`))
	})

	log.Fatal(http.ListenAndServe(":8080", v.Middleware(mux)))
}

📂 Project Structure

.
├── docs/             # Documentation and assets
├── examples/         # Router-specific implementation examples
│   ├── gin/          # Gin-gonic integration
│   ├── gorilla/      # Gorilla Mux integration
│   └── standard/     # Standard net/http integration
├── swagger-ui/       # Embedded Swagger UI assets
├── errors.go         # Custom error handling and encoders
├── options.go        # Configuration options (Functional options pattern)
├── swagger.go        # Swagger UI serving logic
└── validator.go      # Core validation middleware

⚙️ Configuration

Option Description Default
WithValidateRequests(bool) Enable/Disable request validation true
WithValidateResponses(bool) Enable/Disable response validation false
WithSwaggerUIPath(string) Change Swagger UI base path /docs
WithErrorEncoder(ErrorEncoder) Custom error response format DefaultErrorEncoder
WithRouter(routers.Router) Set a custom OpenAPI router gorillamux.NewRouter

🧪 Running Tests

Maintain code quality by running the comprehensive test suite:

# Run all unit tests
go test ./...

# Run tests with coverage
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

🤝 Contributing

Contributions are welcome! Check out the Contribution Guide to get started.

📄 License

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

Additional Resources

Project

Tools