Proposal swag 2.0 using open api 3.0

[Nerzal]

Hey everyone.
As the support of Swagger 2.0 is pretty stable now, we should start to make a list of all features / changes we need to support Open Api 3.0.

We might create a new 2.0 milestone and move/create Open Api 3.0 support issues in there.

[superdave]

I would love this, we've been holding off on it at work because it's not OpenAPI 3. What's best for me to help?

[ubogdan]

@superdave PR is always welcome.

[tylfin]

Would love this to get access to the oneOf functionality for schema responses

[alandtsang]

Does it support OpenAPI Specification 3 now?

[Nerzal]

nope.
The spec lib which is used under the hood does only support Swagger 2.0.

We'd need to switch to a spec lib that supports OpenAPI 3, if there is such a lib by now

[ipfans]

@Nerzal maybe just try https://github.com/getkin/kin-openapi

[OneCricketeer]

I've found a way to generate openapi3 specs from the output of this project

#386 (comment)

[hotrungnhan]

upppppppppppppppppppppppppppppppppppppp!

[vtopc]

Any progress with this? Except for workaround

[ubogdan]

I don't think It will happen any time soon.

[Nerzal]

i have a branch, where i refactore swaggo to use open api 3.0 specs, but will still take some weeks/months until it is finished, as i do not have that much time at hand to complete it

[ubogdan]

We can't support this kind of change overnight.
More than that, this will introduce breaking changes, and this has to go with v2.
On the other hand, we see many requests regarding improvements and bug fixes for the current parser.
Working on a new version too early will introduce the additional overhead of merging the v1 fixes in the new branch.

[vtopc]

i have a branch, where i refactore swaggo to use open api 3.0 specs, but will still take some weeks/months until it is finished, as i do not have that much time at hand to complete it

Could you share the branch?

[Nerzal]

Still lots of work to do, but "soon" i'll have some time.

https://github.com/Nerzal/swag/tree/feature/openapi3

Here is the comparison:
Nerzal@a962819

[guiyomh]

@Nerzal How Can I help you to finish your work?

[santosh]

Is there any alternative project which supports OpenAPI v3? I think we are way behind.

[ubogdan]

@santosh eventually we should offer support on how to migrate from swag.

[Nerzal]

I started a new attempt.

I'm making pretty good progress here.
I can already parse general API info + lots of the operation parts.

Nerzal#5

[ubogdan]

I can make v2 branch for openapi v3 if you want.

[Nerzal]

Sounds good.
My current goal is to implement everything we have now in the OpenAPI 3.1 spec.
As soon as this is working i'll make a PR to the new V2 branch.

[ubogdan]

Done. Please make the PR against this branch https://github.com/swaggo/swag/tree/v2

[Nerzal]

Okay, i'll open a Work in Progress PR now.
We can use that to potentially discuss implementation details.

Some comments like host, basepath and some more do not exist anymore and need a new swag comment syntax.
There are some more examples. I guess some of them could need some discussion, when i come to the point.

I'm currently working full time on this project, so that will happen pretty soon

[ubogdan]

@Nerzal Let's keep it simple. This doesn't mean it has to be done in 1 single PR.
We first need an MVP and we will do a beta release. So the community will have the chance to test and provide feedback.

[hookenz]

would love anyOf to support multiple body schemas

[Nerzal]

I guess we could call it an MVP as soon as response objects and request bodies are correctly parsed, which is what i am working on currently.

My next step is Adding some Tests, as parsing a real world documentation while debugging tends to get pretty complicated.

[Nerzal]

Yes implementing tests helps.
More or less i try to adapt all existing tests

[Nerzal]

The first throw of the implementation is now on the V2 branch. It needs testing, feel free to report issues. I'll try to fix them

[ubogdan]

v2.0.0-beta is avail for testing ...

[Breigner01]

Hi,

I see that a lot of work is being done to implement open API 3.0 specifications, (there are commits dating from last week on branch v2).
Is there an issue or discussion that I could follow to get updated on how this goes and even what needs to be done so that I could even try to help implement certain things?

[eliyahus]

@Nerzal thanks for adding the ability to generate OpenAPI v3.1! Any plans to support generation of OpenAPI 3.0 spec?

[Bijan-Massoumi]

where can I find documentation on 3.1 generation? also how differently do I need to annotate / is it a smooth transition?

[wenqi73]

Any progress on the spec 3.0 generation?

[santosh]

I'd really appreciate if someone could write a blog post (or tutorial video) on how to use the latest v2 of swaggo/swag which uses OpenAPI v3?

[memphis88]

You can use the new version programmatically, e.g.

package main

import (
	"log"

	"github.com/swaggo/swag/v2"
	"github.com/swaggo/swag/v2/gen"
)

func main() {
	err := gen.New().Build(&gen.Config{
		SearchDir: "./",
		MainAPIFile:        "internal/v2/api/service.go",
		PropNamingStrategy: swag.CamelCase,
		OutputDir:          "./docs",
		OutputTypes:        []string{"json", "yaml"},
		ParseDependency:    true,
		// This is a swag/v2 field
		GenerateOpenAPI3Doc: false,
		ParseVendor:        true,
	})

	if err != nil {
		log.Fatalf("Failed to generate swagger.json err: %v", err)
	}
}

I suppose the new flag is also available on the cli, I just haven't tried that. As far as I could tell the new version converts v2 to v3 by using the same annotations but I found it buggy so far.

[rattrayalex]

It seems that development of OpenAPI v3.x has stalled out, is that so? Does anyone have alternative libraries that they can recommend to migrate to?

[obrhoff]

I personally migrated to oapi-codegen. In my opinion, it is better to write the API specification first and then generate the interfaces on the server/clients based on it.

For migration, I used the file generated by Swaggo as a basis to generate the interface. I started making my specification changes directly in the YAML file from that point onward.

[simranjitnagra18]

@Nerzal Any progress on the spec 3.0 generation? When is the expected release date for v2?

[simranjitnagra18]

It seems that development of OpenAPI v3.x has stalled out, is that so? Does anyone have alternative libraries that they can recommend to migrate to?

@rattrayalex did you get any alternative library?

[rattrayalex]

I've heard good things about https://github.com/danielgtaylor/huma but haven't tried it myself.

[8thgencore]

I've heard good things about https://github.com/danielgtaylor/huma but haven't tried it myself.

there is also such a framework that works with go 1.22
https://github.com/go-fuego/fuego