Suggestion: groups and sub-routing

[cardinalby]

Hi! Thanks for the great library, I believe it's the best approach to documenting API in Go ecosystem so far.

Although, I found a batch of issues created by different people here regarding:

• groups (how to define several routing groups with different set of middlewares?)
• sub-routing (how to define sub-route group that will prefix all operations and keep auto-generated operation ids and summaries relevant)

Also, some of the features (Transformers) are available only globally for the API instance and can't be set per operation.

OpenAPI endpoints are registered directly with Adapter and I can't apply middlewares to them (how to add auth for openapi.yml endpoint?)

I believe these issues should be addressed by Huma instead of by tuning underlying routers:

• being aware of that things Huma can create proper operation ids and summaries
• it will be independent of router capabilities
• it would provide consistent user experience and nothing except std http.ServeMux would be needed for a user
• it would make easier to migrate from other routers

I want to use Huma in my company's project, we need all these features to migrate from Gin due to the project structure and heavy usage of gin groups.

I found an elegant way to provide all these features with Huma solely and want you to take a look at it. I believe it can be integrated into Huma with full backward compatibility resolving all the issues you have on Github.

Check out the library and contact me if you would be interested in bringing these features into Huma. I believe it would be even more elegant being a part of Huma rather than a separate library.

Some examples:

🔻 "Base path + tags + middlewares" group

v1gr := api.            // all operations registered with v1gr will have:
	AddBasePath("/v1").                            // - "/v1" base path
	AddOpHandler(op_handler.AddTags("some_tag")).  // - "some_tag" tag
	AddMiddlewares(m1, m2)                         // - m1, m2 middlewares
	
hureg.Get(v1gr, "/cat", ...) // "/v1/cat" with "some_tag" tag and m1, m2 middlewares
hureg.Get(v1gr, "/dog", ...) // "/v1/dog" with "some_tag" tag and m1, m2 middlewares

🔻 Multiple base paths

Sometimes we need to register the same endpoint with multiple base paths (e.g. /v1 and /v2).

multiPathGr := api.AddMultiBasePaths(nil, "/v1", "/v2")

hureg.Get(multiPathGr, "/sparrow", ...) // "/v1/sparrow"
                                        // "/v2/sparrow"

🔻 Transformers per group

trGr := api.AddTransformers(...) // transformers will be applied only to the operations 
                                 // registered in this group

hureg.Get(trGr, "/crocodile", ...)

[braindev]

Check out the library and contact me if you would be interested in bringing these features into Huma.

@cardinalby, I'm not sure how to contact you other than here. FWIW, I think the features your library pair well with ❤️ Huma ❤️. My use case is an API protected by an authentication middleware BUT there are some endpoints which do not need or cannot require authentication. It feels weird to break them out in to a separate API OR have to remember to add the authentication middleware for every API endpoint except the few exceptions (which seems error prone).

Consider a contrived example:

# no need for authentication
POST /api/authentication
POST /api/reset_password
POST /api/create_account
GET  /api/plans

# requires authentication
GET  /api/authentication
... everything else

[cardinalby]

@braindev Hi and thanks :) You are right, it's one of the use-cases I created it for. Same as base paths for groups, middlewares are must-have for routing.

P.S. It's the issue I created hoping to contact the Huma author if he is interested in the features from my lib. If you have questions regarding Hureg usage you can create an issue at Hureg's issues page.

[Jtcruthers]

FWIW, I had a similar issue and solved it via moving the authentication middleware to the router-level, so I could skip the auth middleware on public routes:

func Authenticate(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
      // Ignore public endpoints
      publicRoutes := []string{"/api/authentication", "/api/reset_password", "/api/create_account" }
      for _, route := range publicRoutes {
        if r.URL.Path == route {
          next.ServeHTTP(w, r)
          return
        }
      }
     
    // Continue authentication middleware
     ...

There isn't a huma-first solution AFAIK, but now every route is authenticated unless specified in the middleware. The hureg library looks great though

[cardinalby]

@Jtcruthers that's feasible, but it takes out some of the Huma advantages: declarative routes description. Aside from necessity to duplicate route paths (strictly speaking you should also check HTTP method here), to have nice OpenAPI you need to additionally assign "security" entries for these routes while registering them with Huma. For example, if they are correctly set it's possible to make requests through OpenAPI web explorer (filling the token field) and it's clear for OpenAPI consumer which security protocol particular endpoints expect.

That's the use-case for "operation handlers" in Huma. You can create an operation handler that will add an auth middleware and a corresponding security entry to an operation at once.

You don't even need Hureg in this case (it just makes it more convenient to make it for groups of routes)

[Luks17]

These issues are also blocking my team from migrating from gin. Hureg is really nice, but it would be even better if it was already part of huma.