ginopenapi

ginopenapi

ginopenapi is a minimal adapter for the Gin web framework that connects your routes to an OpenAPI 3.x specification using oaswrap/spec.

This package lets you define your Gin routes and generate OpenAPI docs automatically — with simple, chainable options.

The underlying spec builder uses swaggest/openapi-go — a robust OpenAPI 3.0/3.1 generator for Go with support for struct tags.

✨ Features

• ✅ Integrates Gin routes with an OpenAPI spec.
• ✅ Uses oaswrap/spec powered by swaggest/openapi-go.
• ✅ Supports struct tags for request/response models — automatically maps field properties, examples, and validation.
• ✅ Define common route metadata: summary, description, tags, security, request/response models.
• ✅ Built-in validation and schema generation helpers.

📦 Installation

go get github.com/oaswrap/ginopenapi

⚡️ Quick Start

package main

import (
	"log"

	"github.com/gin-contrib/cors"
	"github.com/gin-gonic/gin"
	"github.com/oaswrap/ginopenapi"
	"github.com/oaswrap/spec/option"
)

func main() {
	r := gin.Default()

	// Optional: Add CORS middleware
	r.Use(cors.New(cors.Config{
		AllowOrigins: []string{"*"},
	}))

	// Setup OpenAPI router
	api := ginopenapi.NewRouter(r,
		option.WithTitle("Example API"),
		option.WithVersion("1.0.0"),
		option.WithDescription("Sample Gin + OpenAPI"),
		option.WithOpenAPIVersion("3.0.3"),
		option.WithServer("http://localhost:8080"),
	)

	// Define a simple group and route
	v1 := api.Group("/api/v1")
	v1.POST("/hello", helloHandler).With(
		option.Summary("Say Hello"),
		option.Request(new(HelloRequest)),
		option.Response(200, new(HelloResponse)),
	)

	// Write spec file (optional)
	if err := api.WriteSchemaTo("openapi.yaml"); err != nil {
		log.Fatal(err)
	}
	log.Println("✅ OpenAPI schema written to: openapi.yaml")

	log.Printf("🚀 OpenAPI docs available at: %s", "http://localhost:8080/docs")

	r.Run(":8080")
}

// helloHandler handles the /api/v1/hello route
func helloHandler(c *gin.Context) {
	var req HelloRequest
	if err := c.ShouldBindJSON(&req); err != nil {
		c.JSON(400, gin.H{"error": "Invalid request body"})
		return
	}
	c.JSON(200, HelloResponse{
		Message: "Hello, " + req.Name,
	})
}

// Request and response types
type HelloRequest struct {
	Name string `json:"name" example:"World" binding:"required"`
}

type HelloResponse struct {
	Message string `json:"message" example:"Hello, World"`
}

For a full working version, see the examples directory.

This example demonstrates:

• Nested groups (/pets)
• Multiple HTTP methods (GET, POST, PUT, DELETE)
• With options for detailed spec generation
• Use of struct tags to enrich models automatically.

📚 Documentation

• 📦 oaswrap/spec — the core OpenAPI builder.
• 🧩 swaggest/openapi-go — the underlying OpenAPI engine.
• 📖 Gin — the web framework.
• 📚 pkg.go.dev/github.com/oaswrap/ginopenapi

🤝 Contributing

PRs and issues welcome!
If you find bugs or want to improve adapters or helpers, please open an issue.

📄 License

MIT

Made with ❤️ by oaswrap