search

ogen-go / ogen

OpenAPI v3 code generator for go
https://ogen.dev
Apache License 2.0
1.19k stars 71 forks source link

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

Open lrstanley opened 2 months ago

lrstanley commented 2 months ago

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:

https://github.com/ogen-go/ogen/blob/b41f78c97d1733bbc507b0118f76b926c93c947d/spec.go#L83-L84

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 commented 1 week ago

+1 for this i opened a issue in ent for the same problem https://github.com/ent/ent/issues/4108

When I found this:

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 commented 5 days ago

Implemented here: https://github.com/ogen-go/ogen/pull/1269

prgres commented 2 days ago

@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 commented 2 days ago

you can watch the status here https://github.com/ent/contrib/pull/590

lrstanley commented 2 days ago

@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 commented 2 days ago

@prgres looks like https://github.com/ogen-go/ogen/pull/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.