extensions: support providing extensions in ogen.Spec, that can be marshalled to JSON

[lrstanley]

Description

I have a project that uses entgo and its associated extension entoas to generate a schema specification using ogen. It does this by using the ent graph, which has all type information and annotations to control what to add and exclude from the specification. This works relatively well today, however, it currently isn't possible to add OpenAPI extensions (x-<etc>) to the spec, and have it be marshalled to JSON.

This looks to be due to the json:"-" struct tags on all of the related extension fields, for example:

ogen/spec.go

Lines 83 to 84 in b41f78c

	// Specification extensions.
	Extensions Extensions `json:"-" yaml:",inline"`

I suspect this is due to encoding/json not supporting inlining for non-embedded fields, however, I am wondering if there is a way around this (maybe marshal to yaml, then to json in all MarshalJSON() methods, if the yaml encoder supports inlining? Maybe go-faster/jx could be used (or may be overkill?)

References

n/a

[prgres]

+1 for this i opened a issue in ent for the same problem ent/ent#4108

When I found this:

• Proposal: Allow grouping operations into separate handlers #1207
• feat(gen): add support for x-ogen-operation-group extension #1222

I really liked the idea to incorporate this. What I am doing now is creating a wrapper over the ogen.Spec structure and implementing the very own marshalling function. It is no ideal because i messes up the fields order in json file.

[prgres]

Implemented here: #1269

[prgres]

@lrstanley the logic merged. I am working now on the PR to the entoas's codebase to incorporated that. The basics are already there and a pr should be submitted today but it has to wait for the new ogen release

[prgres]

you can watch the status here ent/contrib#590

[lrstanley]

@prgres looks like #1269 only covers Operation and PathItem levels, however, extensions can be provided in many other places, all of which should probably be supported.

Additionally, looking at the approach required to set the extensions, it feels rather painful having to interact with yaml.Node directly.

I will likely keep this open for those reasons -- I may submit a PR when I get around to it.

As an aside, @prgres, keep an eye out for https://github.com/lrstanley/entrest -- I ran into many problems with entoas (and sister library ogent), in addition to its limited support for a lot of features I wanted (pagination, sorting, filtering, efficient/compliant OpenAPI spec, among other things). It also has direct support for an HTTP server/handler implementation (that supports all of the advanced features like pagination, filtering, etc). entrest isn't ready just yet, but I'm actively working towards v1. Will have full documentation to follow as well.

[prgres]

@prgres looks like #1269 only covers Operation and PathItem levels, however, extensions can be provided in many other places, all of which should probably be supported.

@lrstanley That's true because I was mainly focused on implementing the x-ogen-operation-group to split handlers.

I will def checkout the entrest - looks very promising. And I cannot agreed more on the contrib/entoas repo but would add lack of docs and lack of responses from maintainers...

With saying that, I may even help you with yours.