README
¶
echoopenapi
echoopenapi is a minimal adapter for the Echo web framework that connects your routes to an OpenAPI 3.x specification using oaswrap/spec.
This package lets you define your Echo 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 Echo routes with an OpenAPI spec.
- ✅ Uses
oaswrap/specpowered byswaggest/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/echoopenapi
⚡️ Quick Start
package main
import (
"log"
"github.com/labstack/echo/v4"
"github.com/oaswrap/echoopenapi"
"github.com/oaswrap/spec/option"
)
func main() {
e := echo.New()
r := echoopenapi.NewRouter(e,
option.WithTitle("My API"),
option.WithDescription("This is a sample API"),
option.WithVersion("1.0.0"),
)
v1 := r.Group("/api/v1")
v1.POST("/hello", helloHandler).With(
option.Summary("Say Hello"),
option.Description("Returns a greeting message"),
option.OperationID("sayHello"),
option.Tags("greeting"),
option.Request(new(HelloRequest)),
option.Response(200, new(HelloResponse)),
)
// Write spec file (optional)
if err := r.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:3000/docs")
e.Logger.Fatal(e.Start(":3000"))
}
// helloHandler handles the /api/v1/hello route
func helloHandler(c echo.Context) error {
var req HelloRequest
if err := c.Bind(&req); err != nil {
return c.JSON(400, map[string]string{
"title": "Bad Request",
"detail": "Invalid request data: " + err.Error(),
})
}
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.
📚 Documentation
- 📦 oaswrap/spec — the core OpenAPI builder.
- 🧩 swaggest/openapi-go — the underlying OpenAPI engine.
- 📖 Echo — the web framework.
- 📚 pkg.go.dev/github.com/oaswrap/echoopenapi
🤝 Contributing
PRs and issues welcome!
If you find bugs or want to improve adapters or helpers, please open an issue.
📄 License
Made with ❤️ by oaswrap
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Generator ¶
type Generator interface {
Router
// Validate checks if the OpenAPI specification is valid.
Validate() error
// GenerateSchema generates the OpenAPI schema.
// Defaults to YAML. Pass "json" to generate JSON.
GenerateSchema(format ...string) ([]byte, error)
// MarshalYAML marshals the OpenAPI schema to YAML.
MarshalYAML() ([]byte, error)
// MarshalJSON marshals the OpenAPI schema to JSON.
MarshalJSON() ([]byte, error)
// WriteSchemaTo writes the schema to the given file.
// The format is inferred from the file extension.
WriteSchemaTo(filepath string) error
}
Generator defines an Echo-compatible OpenAPI generator.
It combines routing and OpenAPI schema generation.
func NewGenerator ¶
func NewGenerator(e *echo.Echo, opts ...option.OpenAPIOption) Generator
NewGenerator creates a new OpenAPI generator with the provided Echo instance and options.
It initializes the OpenAPI configuration and sets up the necessary routes for serving
type Route ¶
type Route interface {
// Method returns the HTTP method (GET, POST, etc.).
Method() string
// Path returns the route path.
Path() string
// Name returns the route name.
Name() string
// With applies OpenAPI operation options to this route.
With(opts ...option.OperationOption) Route
}
Route represents a single Echo route with OpenAPI metadata.
type Router ¶
type Router interface {
// GET registers a new GET route.
GET(path string, handler echo.HandlerFunc, m ...echo.MiddlewareFunc) Route
// POST registers a new POST route.
POST(path string, handler echo.HandlerFunc, m ...echo.MiddlewareFunc) Route
// PUT registers a new PUT route.
PUT(path string, handler echo.HandlerFunc, m ...echo.MiddlewareFunc) Route
// DELETE registers a new DELETE route.
DELETE(path string, handler echo.HandlerFunc, m ...echo.MiddlewareFunc) Route
// PATCH registers a new PATCH route.
PATCH(path string, handler echo.HandlerFunc, m ...echo.MiddlewareFunc) Route
// HEAD registers a new HEAD route.
HEAD(path string, handler echo.HandlerFunc, m ...echo.MiddlewareFunc) Route
// OPTIONS registers a new OPTIONS route.
OPTIONS(path string, handler echo.HandlerFunc, m ...echo.MiddlewareFunc) Route
// TRACE registers a new TRACE route.
TRACE(path string, handler echo.HandlerFunc, m ...echo.MiddlewareFunc) Route
// CONNECT registers a new CONNECT route.
CONNECT(path string, handler echo.HandlerFunc, m ...echo.MiddlewareFunc) Route
// Add registers a new route with the given method, path, and handler.
Add(method, path string, handler echo.HandlerFunc, m ...echo.MiddlewareFunc) Route
// Group creates a new sub-group with the given prefix and middleware.
Group(prefix string, m ...echo.MiddlewareFunc) Router
// Use adds global middleware.
Use(m ...echo.MiddlewareFunc) Router
// File serves a single static file.
File(path, file string)
// FileFS serves a static file from the given filesystem.
FileFS(path, file string, fs fs.FS, m ...echo.MiddlewareFunc)
// Static serves static files from a directory under the given prefix.
Static(prefix, root string)
// StaticFS serves static files from the given filesystem.
StaticFS(prefix string, fs fs.FS)
// With applies OpenAPI group options to this router.
With(opts ...option.GroupOption) Router
}
Router defines an OpenAPI-aware Echo router.
It wraps Echo routes and supports OpenAPI metadata.
Source Files
Directories
Click to show internal directories.
Click to hide internal directories.