Documentation generation with new group feature

[bbedward]

Hi,

Love the framework - it is a huge time saver and a great project.

Groups was added in #728 , however it would be great if the documentation generated included the group path.

For example:

	// /auth group
	authGrp := huma.NewGroup(api, "/auth")
	huma.Get(authGrp, "/login", srvImpl.Login)
	huma.Get(authGrp, "/callback", srvImpl.Callback)

	// /user group
	userGrp := huma.NewGroup(api, "/user")
	userGrp.UseMiddleware(mw.Authenticate)
	huma.Get(userGrp, "/me", srvImpl.Me)

I have a /auth group and a /user group

In the documentation/openapi generation the names are just "get login" "get callback" "get me" - it would be nice if the documentation would include the group path as well. So it would be "get auth login", "get user me", "get auth callback"

Screenshot shows what I'm referring to:

And the openapi.yaml summary:

  /user/me:
    get:
      operationId: get-me
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MeResponseBody"
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ErrorModel"
          description: Error
      summary: Get me

[danielgtaylor]

@bbedward thanks for the feedback! I'll see what can be done, but keep in mind the auto-generation is best-effort and won't work for all use-cases. You can always use huma.Register instead of huma.Get and provide your own operation ID and summary!

[thnee]

I found the feature to specify Tags as an argument to huma.Operation when doing huma.Register, which creates a form of grouping in the docs. This is pretty neat, however: A) The endpoints are grouped in the docs, but their associated schemas are not, schemas are still in a single global pile below the endpoints. B) It does not generalize anything else either, such as operation id or path. C) It does not seem to be integrated with the group feature.

Both endpoints and schemas are typically stored in separate packages in the source code, as a form of grouping. It would be good to be able to do the same sort of grouping for huma.Register.

For example, I have a code package called iam with an endpoint to get the current account. To get everything separated, I now have to specify iam several times in the code. If there is some way to only specify "iam" once for all this, I think that would be quite useful. Although, I guess I would want to specify it twice to be complete, something like huma.Group{ID: "iam", Name: "IAM"}.

type IAMGetAccountOutput struct {Body struct {}}

func (r Routes) GetAccount(ctx context.Context, input *struct{}) (*IAMGetAccountOutput, error) {}

func RegisterRoutes(api huma.API) {
	routes := Routes{}
	huma.Register(
		api,
		huma.Operation{
			OperationID: "iam-account",
			Method:      http.MethodGet,
			Path:        "/iam/account",
			Summary:     "Get account",
			Tags:        []string{"IAM"},
		},
		routes.GetAccount,
	)
}

I could of course do some of these things with a helper variable myself. But I think it would be useful if the framework had support for this. In either case, there's still the issue of grouping schemas along with their endpoints.

Do I understand correctly that there is currently no way to group schemas in the docs? Other than manually adding a prefix to each struct name as shown here.

Although, now I am also looking into the possibility of maybe just excluding/hiding the schema section in the docs. Not sure how or if it makes sense yet.