Skip to content

About

Generate OpenCollection files for Bruno from Gin, Echo, Fiber, Chi or net/http routes

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Latest commit

 

History

12 Commits

Folders and files

Repository files navigation

go-opencollection-generator

A go generate tool that introspects HTTP router registrations and emits OpenCollection YAML files for use with Bruno.

Supports Gin, Echo, Fiber, Chi, and the standard net/http package.

Installation

go install github.com/robertjndw/go-opencollection-generator/cmd/go-opencollection-generator@latest

Usage

Add a //go:generate directive to your project:

//go:generate go-opencollection-generator -name "My API" -output ./collection -framework gin

Then run:

go generate ./...

Or invoke directly:

go-opencollection-generator \
  -name "My API" \
  -framework gin \
  -package ./internal/server \
  -output ./collection \
  -author "Alice" \
  -version "1.0.0" \
  -base-url "{{baseUrl}}" \
  -env-name "Local" \
  -env-base-url "http://localhost:8080"

Flags

Flag Default Description
-name (required) Collection name
-framework gin HTTP framework to parse (gin, echo, fiber, chi, nethttp)
-output ./collection Output directory for generated YAML files
-package . Package directory to analyze
-version 1.0.0 Collection version
-author Author name
-base-url {{baseUrl}} Base URL expression prepended to all request paths
-env-name Generate a collection environment with this name
-env-base-url Set the generated environment's baseUrl variable value
-env-color Set the generated environment color
-bundled false Write a single bundled YAML file instead of a directory hierarchy
-prune false Remove generated files/items that no longer exist in source code

Output modes

Filesystem mode (default, -bundled=false): writes a directory hierarchy that mirrors the route group structure. Each request becomes an individual .yml file; each route group becomes a subdirectory.

collection/
  opencollection.yml   # collection metadata
  ping.yml             # top-level route
  api-v1/
    folder.yml
    list-users.yml
    admin/
      folder.yml
      delete-user.yml

Bundled mode (-bundled): writes a single <name>.yml file containing the entire collection inline.

Environments

If you want the generator to create an OpenCollection environment, pass -env-name and -env-base-url.

In bundled mode, the generated collection will include:

config:
  environments:
    - name: Local
      variables:
        - name: baseUrl
          value: http://localhost:8080

Requests will continue to use {{baseUrl}}/..., but baseUrl will come from the collection environment instead of being added as a per-request runtime variable.

In filesystem mode, the generator writes environments to dedicated files under environments/, for example environments/local.yml.

Supported frameworks

Gin

r := gin.Default()
r.GET("/ping", Ping)
v1 := r.Group("/api/v1")
v1.GET("/users/:id", GetUser)
  • Methods: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, Any
  • Groups: r.Group("/prefix") → folder
  • Chaining: r.Group("/api").GET("/health", Handler)
  • Path params: :param and *wildcard → {param} placeholders

Echo

e := echo.New()
e.GET("/ping", Ping)
g := e.Group("/api/v1")
g.GET("/users/:id", GetUser)
  • Same patterns as Gin (uppercase methods, .Group(), :param syntax)

Fiber

app := fiber.New()
app.Get("/ping", Ping)
api := app.Group("/api/v1")
api.Get("/users/:id", GetUser)
  • PascalCase methods: Get, Post, Put, Delete, Patch, Head, Options, All
  • Groups: app.Group("/prefix")
  • Path params: :param → {param} placeholders

Chi

r := chi.NewRouter()
r.Get("/ping", Ping)
r.Route("/api/v1", func(r chi.Router) {
    r.Get("/users/{id}", GetUser)
    r.Route("/admin", func(r chi.Router) {
        r.Delete("/users/{id}", DeleteUser)
    })
})
  • PascalCase methods: Get, Post, Put, Delete, Patch, Head, Options
  • Groups: r.Route("/prefix", func(r chi.Router) {...}) → folder
  • Middleware groups: r.Group(func(r chi.Router) {...}) — no folder created
  • Path params: {param} (native, no conversion needed)

net/http

mux := http.NewServeMux()
mux.HandleFunc("GET /ping", Ping)
mux.HandleFunc("GET /users/{id}", GetUser)
  • Uses Go 1.22+ enhanced patterns with the HTTP method embedded in the pattern string
  • Handles both HandleFunc and Handle
  • No group concept (all routes are top-level)
  • Path params: {param} (native, no conversion needed)

Path parameters

All frameworks normalize path parameters to the {param} format in the generated output:

Framework Source syntax Generated URL
Gin / Echo / Fiber :id /users/{{id}}
Chi / net/http {id} /users/{{id}}

Path parameters also appear as explicit path parameter entries in each request's params list.

Examples

Framework Example
Gin examples/simple-api-gin/
Echo examples/simple-api-echo/
Fiber examples/simple-api-fiber/
Chi examples/simple-api-chi/
net/http examples/simple-api-nethttp/

To generate the OpenCollection YAML files for an example, run go generate inside its directory.

Requirements

  • Go 1.25+
  • The target package must be loadable via go/packages (i.e. a valid Go module)

Development

go build ./...
go vet ./...
go test ./...       # includes schema validation tests against docs/schema.json

About

Generate OpenCollection files for Bruno from Gin, Echo, Fiber, Chi or net/http routes

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages