Proposal: Allow grouping operations into separate handlers

[johnrutherford]

If you have a large API, having many operations on a single Handler interface can make it difficult to reasonably split up your implementation code. Many API frameworks are based on "controllers" which allow you to group related operations, and each controller can have dependencies necessary for just those operations.

Description

I propose allowing the user to group operations and generate a separate handler interface for each group. The main Handler interface would embed all of these operation group interfaces.

The operation group would be specified using an x-ogen-operation-group extension field on the Path Item Object or Operation Object. If set on the Path Item, the group would apply to all child Operations unless overridden on an Operation. This would allow creating arbitrary groups based on version, resource, etc. The group name would be treated as case-insensitive.

The name of the generated group handler interface would be the group name converted to PascalCase with a "Handler" suffix. Any operations without a group would remain on the main Handler interface. The NewError function for the Convenient errors feature would also remain on the Handler interface.

As proposed, this feature would be opt-in and backwards-compatible. Users with existing implementations could create operation groups incrementally.

I'd be happy to create PR for this if the proposal sounds good.

Example

Taking the OpenAI API example, you could split up the operations by resource. The generated code would look something like this:

type Handler interface {
	AnswersHandler
	FilesHandler
	ImagesHandler
	...
}

// x-ogen-operation-group: answers
type AnswersHandler interface {
	CreateAnswer(ctx context.Context, req *CreateAnswerRequest) (*CreateAnswerResponse, error)
}

// x-ogen-operation-group: files
type FilesHandler interface {
	CreateFile(ctx context.Context, req *CreateFileRequestMultipart) (OpenAIFile, error)
	DeleteFile(ctx context.Context, params DeleteFileParams) (*DeleteFileResponse, error)
	DownloadFile(ctx context.Context, params DownloadFileParams) (string, error)
	ListFiles(ctx context.Context) (*ListFilesResponse, error)
	RetrieveFile(ctx context.Context, params RetrieveFileParams) (OpenAIFile, error)
}

// x-ogen-operation-group: images
type ImagesHandler interface {
	CreateImage(ctx context.Context, req *CreateImageRequest) (ImagesResponse, error)
	CreateImageEdit(ctx context.Context, req *CreateImageEditRequestMultipart) (ImagesResponse, error)
	CreateImageVariation(ctx context.Context, req *CreateImageVariationRequestMultipart) (ImagesResponse, error)
}
...

The Handler implementation could be composed from the handler implementations.

// answers.go
type answersHandler struct {
	// dependencies
}

func (a *answersHandler) CreateAnswer(ctx context.Context, req *CreateAnswerRequest) (*CreateAnswerResponse, error) {
	...
}

var _ AnswersHandler = (*answersHandler)(nil)

// handler.go
type handler struct {
	AnswersHandler
	AudioHandler
	...
}

var _ Handler = (*handler)(nil)

Open Questions

• Should we also allow grouping webhook handlers with this extension field?
• Do we need to generate "unimplemented" structs for each handler interface?

References

The contiamo/openapi-generator-go project uses a similar extension field for grouping operations.