swag
swag copied to clipboard
swaggo
Proposal swag 2.0 using open api 3.0
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.
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?
Would love this to get access to the oneOf functionality for schema responses
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
I've found a way to generate openapi3 specs from the output of this project
https://github.com/swaggo/swag/issues/386#issuecomment-833913287
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
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.
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?
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: https://github.com/Nerzal/swag/commit/a9628192bf1e857e210bd9b5c85c6953bb7b1f6c
Is there any alternative project which supports OpenAPI v3? I think we are way behind.
I started a new attempt.
I'm making pretty good progress here. I can already parse general API info + lots of the operation parts.
https://github.com/Nerzal/swag/pull/5
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.
Done. Please make the PR against this branch https://github.com/swaggo/swag/tree/v2
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
@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.
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.
Yes implementing tests helps. More or less i try to adapt all existing tests
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
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?
@Nerzal thanks for adding the ability to generate OpenAPI v3.1! Any plans to support generation of OpenAPI 3.0 spec?
