Support Spec Generation

[mkadirtan]

Spec generation for both OpenAPI and JSON Schema would be great. This might also open the door for generating code from those specs.

[Oudwins]

This is a very interesting idea. Although I will say that its something that would have to come after v1 as a helper package and not part of Zog Core.

Have you given some thought as to how this could be implemented? Zog is http framework agnostic. Generally OpenAPI schema generation wraps around a HTTP framework or uses something like code annotations. There doesn't seem to be many good solutions in GO though, this is what I could find:

• https://github.com/a-h/rest
• https://github.com/go-fuego/fuego
• https://huma.rocks/

[cachesdev]

Huma is really good. It think it should be possible to do json schema gen or openapi just based on the validation schemas, but yeah maybe as a plugin.

[Oudwins]

Yes it should be possible to create Json schemas based on Zog schemas but only for the API request data. But openapi is so much more than just request data, it displays:

• Endpoints
• The expected request data for those endpoints
• The response data for those endpoints and status codes
• and more

The only approach I can think of that might make sense for Zog is to create a plugin for one of the frameworks/libs mentioned above that will fill in the schema for the request data and let the framework handle everything else.

Edit: up on further thought. I think the best way to solve this is to create a plugin/package that allows for the conversion of Zog schemas into an intermediate textual or json representation which can then be converted to openapi, swagger or any other. Additionally, like @mkadirtan mentioned this would open up the possibility to generate Zog schemas from things like openapi.

Let me consider this further as we move towards v1. If you have any additional thoughts/ideas related to this do leave them here! But with the knowledge that I will probably not be working on this until v1 is out.

[mkadirtan]

@Oudwins

Yes it should be possible to create Json schemas based on Zog schemas but only for the API request data.

You are right, and if you would think about using zog schemas for json serialization ( probably due to performance reasons, instead of validation ), you could have access to response schemas, too.

[mkadirtan]

@Oudwins

Yes it should be possible to create Json schemas based on Zog schemas but only for the API request data.

You are right, and if you would think about using zog schemas for json serialization ( probably due to performance reasons, instead of validation ), you could have access to response schemas, too.

On second thought, this would not be a good idea. I come from a Node.js background, and I realized my thought process follows the ideas from the Node.js ecosystem, which doesn't make sense here.

[Oudwins]

@mkadirtan no worries. Mind sharing how you came to that conclusion?

Mostly my thoughts were "sure, but generally you need to validate data coming in, not going out. That would be quite a bit of additional overhead for little gain specially since go is already statically typed. But if you really wanted to enforce a specific contract I guess you could do it".

Not sure if I am missing something

[mkadirtan]

@mkadirtan no worries. Mind sharing how you came to that conclusion?

Mostly my thoughts were "sure, but generally you need to validate data coming in, not going out. That would be quite a bit of additional overhead for little gain specially since go is already statically typed. But if you really wanted to enforce a specific contract I guess you could do it".

Not sure if I am missing something

Haha, exactly these thoughts! In addition, that could also be useful in terms of performance. However, the gain is much bigger on Node.js projects, I don't know if it makes any significant difference in Go.

[Oudwins]

Another nice idea that came up is that this would open the door to importing schemas from Zod which I think is very nice. Just dropping it here so I don't forget when I decide to work on this

[mkadirtan]

I may be able to work on this if you want to. No promises but we might use this for a project at work, and I can convince my manager 🤞

[Oudwins]

That would be awesome. If there is anything I can do to help please let me know!

[Oudwins]

Another very nice possibility this would open up is to generate the structs based on the zog schemas through some kind of CLI

[mkadirtan]

@Oudwins not at the moment, I took a quick look into the codebase and it seems like schema generation would be pretty straightforward, but this is software development so nothing is certain upfront 😅 And CLI features are always awesome, too. I am glad you consider this feature request valuable 🙌🏻

[Oudwins]

Brilliant. I do think Zog is made in such a way as to be quite simple to extend and understand the code!

I'm looking forward to seeing this develop then!

The main things I would want from this are:

1. To have the code for this be as separated as possible from Zog core so we included as little code as possible in end user binaries (specially for people not using this feature)
2. From what I have seen openapi & JSON schema won't support every feature Zog has so ideally we can have a json representation of a zog schema which can then be easily converted to both openapi, JSON schema and anything else we might want