New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

open API 3.0 spec support #128

Open
leslie-wang opened this Issue Jan 31, 2017 · 32 comments

Comments

Projects
None yet
@leslie-wang

leslie-wang commented Jan 31, 2017

OpenAPI will release version 3.0 at Feb 28, 2017. https://www.openapis.org/blog/2017/01/24/a-new-year-a-new-specification. It would be useful if this tool can support 3.0 as well.

@AlJohri

This comment has been minimized.

Show comment
Hide comment
@AlJohri

AlJohri Mar 13, 2017

@whitlockjc I was wondering if there's any plans to start supporting the OpenAPI 3.0 spec. Thanks!

AlJohri commented Mar 13, 2017

@whitlockjc I was wondering if there's any plans to start supporting the OpenAPI 3.0 spec. Thanks!

@whitlockjc

This comment has been minimized.

Show comment
Hide comment
@whitlockjc

whitlockjc Mar 17, 2017

Member

We definitely plan on supporting it but I'm not 100% sure how to do it yet. In swagger-tools, a lot of heft and complexity comes from having a single library with support for multiple specs in it. I need to figure out how I want to support this.

Note: OpenAPI 3.0 is NOT GA yet but now that the Implementer's Draft is out, we should start working on this soon.

Member

whitlockjc commented Mar 17, 2017

We definitely plan on supporting it but I'm not 100% sure how to do it yet. In swagger-tools, a lot of heft and complexity comes from having a single library with support for multiple specs in it. I need to figure out how I want to support this.

Note: OpenAPI 3.0 is NOT GA yet but now that the Implementer's Draft is out, we should start working on this soon.

@gooftroop

This comment has been minimized.

Show comment
Hide comment
@gooftroop

gooftroop Aug 21, 2017

Any update on this now that it's GA?

gooftroop commented Aug 21, 2017

Any update on this now that it's GA?

@whitlockjc

This comment has been minimized.

Show comment
Hide comment
@whitlockjc

whitlockjc Aug 23, 2017

Member

We're wrapping up the next sway release, bug/security fixes and enhancements. After that, 3.0 support will be our top priority. Sorry for the delay.

Member

whitlockjc commented Aug 23, 2017

We're wrapping up the next sway release, bug/security fixes and enhancements. After that, 3.0 support will be our top priority. Sorry for the delay.

@nomadtechie

This comment has been minimized.

Show comment
Hide comment
@nomadtechie

nomadtechie Oct 5, 2017

@whitlockjc is there anything you need help with to get 3.0 support out? Happy to contribute.

nomadtechie commented Oct 5, 2017

@whitlockjc is there anything you need help with to get 3.0 support out? Happy to contribute.

@osher

This comment has been minimized.

Show comment
Hide comment
@osher

osher Jan 30, 2018

@whitlockjc - same question here. If it'd help if I join the effort - please contact me. theganyo has my private mail as I did some PRs for swagger-node-runner / bagpipes.

osher commented Jan 30, 2018

@whitlockjc - same question here. If it'd help if I join the effort - please contact me. theganyo has my private mail as I did some PRs for swagger-node-runner / bagpipes.

@amarzavery

This comment has been minimized.

Show comment
Hide comment
@amarzavery

amarzavery May 30, 2018

@whitlockjc - Any plans to move to 3.0 Open API spec? 3.0 is GA now. Folks have been asking for this since last year. I know you are super busy. We really love this library. It would be great if you can provide an approximate timeline on when will this be possible?

amarzavery commented May 30, 2018

@whitlockjc - Any plans to move to 3.0 Open API spec? 3.0 is GA now. Folks have been asking for this since last year. I know you are super busy. We really love this library. It would be great if you can provide an approximate timeline on when will this be possible?

@osher

This comment has been minimized.

Show comment
Hide comment
@osher

osher Jun 5, 2018

Guys, I suppose it's down to us to fork and get on with it. Or maybe start from scratch in pure ES7 porting the good stuff.
Sadly, my current occupation does not involve swagger at all, but if it did - I't totally would have started by now. But my current position does not leave me much free time for efforts that do not promote the projects' main goals

osher commented Jun 5, 2018

Guys, I suppose it's down to us to fork and get on with it. Or maybe start from scratch in pure ES7 porting the good stuff.
Sadly, my current occupation does not involve swagger at all, but if it did - I't totally would have started by now. But my current position does not leave me much free time for efforts that do not promote the projects' main goals

@whitlockjc

This comment has been minimized.

Show comment
Hide comment
@whitlockjc

whitlockjc Jun 5, 2018

Member

I don’t see why threatening to fork is required when a PR, or PRs, would suffice. I’ve been the only active developer in this project from day one and like you, I’ve run into time conflicts lately. I’ve been trying to pick it back up (look at yesterday’s commits) but it’s not going to ever be as quick if I’m the only one doing it. 3.0 support will likely take some time and will likely require changing the architecture a bit but I’m more than happy to be involved. I will just need some help. If you think a fork is the best approach, by all means.

Member

whitlockjc commented Jun 5, 2018

I don’t see why threatening to fork is required when a PR, or PRs, would suffice. I’ve been the only active developer in this project from day one and like you, I’ve run into time conflicts lately. I’ve been trying to pick it back up (look at yesterday’s commits) but it’s not going to ever be as quick if I’m the only one doing it. 3.0 support will likely take some time and will likely require changing the architecture a bit but I’m more than happy to be involved. I will just need some help. If you think a fork is the best approach, by all means.

@amarzavery

This comment has been minimized.

Show comment
Hide comment
@amarzavery

amarzavery Jun 5, 2018

I don't think it was a threat of any kind. All of us love this repo and the work done by you over here. Since you are the main and only author of this repo, people are expecting a response from you on 3.0 support. @osher posted a comment on Jan 30 and I posted one 7 days ago asking for a timeline if any. This gives us the idea about where the project is heading with 3.0. It took slightly strong words from @osher for you to respond.

Anyways, I can completely understand the time constraints and you working on this project in extra time. More hands on this project would definitely help. I shall discuss this with my team to see what is the priority for 3.0 support and based on that would love to contribute in keeping this project open api 3.0 compliant.

Thank you once again for your response. Have a good day 👍 .

amarzavery commented Jun 5, 2018

I don't think it was a threat of any kind. All of us love this repo and the work done by you over here. Since you are the main and only author of this repo, people are expecting a response from you on 3.0 support. @osher posted a comment on Jan 30 and I posted one 7 days ago asking for a timeline if any. This gives us the idea about where the project is heading with 3.0. It took slightly strong words from @osher for you to respond.

Anyways, I can completely understand the time constraints and you working on this project in extra time. More hands on this project would definitely help. I shall discuss this with my team to see what is the priority for 3.0 support and based on that would love to contribute in keeping this project open api 3.0 compliant.

Thank you once again for your response. Have a good day 👍 .

@whitlockjc

This comment has been minimized.

Show comment
Hide comment
@whitlockjc

whitlockjc Jun 5, 2018

Member

Well, let's make this happen. I'm putting in the time now and I'd love some help. My plan is to release 2.0.0 by EOW (barring any unexpected conflict) and then focusing on OAI v3.x support.

Member

whitlockjc commented Jun 5, 2018

Well, let's make this happen. I'm putting in the time now and I'd love some help. My plan is to release 2.0.0 by EOW (barring any unexpected conflict) and then focusing on OAI v3.x support.

@osher

This comment has been minimized.

Show comment
Hide comment
@osher

osher Jun 9, 2018

osher commented Jun 9, 2018

@celalo

This comment has been minimized.

Show comment
Hide comment
@celalo

celalo Jul 25, 2018

Any news on OAI v3.x support?

celalo commented Jul 25, 2018

Any news on OAI v3.x support?

@whitlockjc

This comment has been minimized.

Show comment
Hide comment
@whitlockjc

whitlockjc Jul 25, 2018

Member

Now that sway@v2.0.0 is released, OASv3.x support is the next major feature being worked on for sway.

Member

whitlockjc commented Jul 25, 2018

Now that sway@v2.0.0 is released, OASv3.x support is the next major feature being worked on for sway.

@celalo

This comment has been minimized.

Show comment
Hide comment
@celalo

celalo Jul 25, 2018

Thank you very much for your immense efforts. I believe, OASv3.x support will need quite a lot of work but do you have a rough timeframe? Do you think it will take days, weeks or months? (I also presume, OASv3.x support will not land to swagger-tools project, since it's deprecated in favor of sway)

celalo commented Jul 25, 2018

Thank you very much for your immense efforts. I believe, OASv3.x support will need quite a lot of work but do you have a rough timeframe? Do you think it will take days, weeks or months? (I also presume, OASv3.x support will not land to swagger-tools project, since it's deprecated in favor of sway)

@whitlockjc

This comment has been minimized.

Show comment
Hide comment
@whitlockjc

whitlockjc Jul 25, 2018

Member

I honestly have no idea how long it will take. Last I heard, OAS@v3.x doesn't even have a JSON Schema to use yet. So I need to figure out how that looks, what the delta is and go from there. I don't think the sway API itself will change much since the JavaScript objects we expose shouldn't change much and when it comes to the features available on them, they shouldn't change much either. Just know, this is me taking a guess and this could all be grossly inaccurate. ;)

Member

whitlockjc commented Jul 25, 2018

I honestly have no idea how long it will take. Last I heard, OAS@v3.x doesn't even have a JSON Schema to use yet. So I need to figure out how that looks, what the delta is and go from there. I don't think the sway API itself will change much since the JavaScript objects we expose shouldn't change much and when it comes to the features available on them, they shouldn't change much either. Just know, this is me taking a guess and this could all be grossly inaccurate. ;)

@whitlockjc

This comment has been minimized.

Show comment
Hide comment
@whitlockjc

whitlockjc Jul 25, 2018

Member

Excuse my naivety...

Member

whitlockjc commented Jul 25, 2018

Excuse my naivety...

@philsturgeon

This comment has been minimized.

Show comment
Hide comment
@philsturgeon

philsturgeon Jul 25, 2018

They OpenAPI folks are still working on that, but this v3.0 metachema is usable despite being labeled as WIP. OAI/OpenAPI-Specification#1270

It’s being used in a lot of tools like oas-kit: https://github.com/Mermade/oas-kit/tree/master/packages/oas-validator/schemas

philsturgeon commented Jul 25, 2018

They OpenAPI folks are still working on that, but this v3.0 metachema is usable despite being labeled as WIP. OAI/OpenAPI-Specification#1270

It’s being used in a lot of tools like oas-kit: https://github.com/Mermade/oas-kit/tree/master/packages/oas-validator/schemas

@whitlockjc

This comment has been minimized.

Show comment
Hide comment
@whitlockjc

whitlockjc Jul 25, 2018

Member

Fair enough. I'm on the TSC and I know that it's a WIP but building on top of a WIP worries me a little, although I'm not against it.

Member

whitlockjc commented Jul 25, 2018

Fair enough. I'm on the TSC and I know that it's a WIP but building on top of a WIP worries me a little, although I'm not against it.

@philsturgeon

This comment has been minimized.

Show comment
Hide comment
@philsturgeon

philsturgeon Jul 25, 2018

philsturgeon commented Jul 25, 2018

@whitlockjc

This comment has been minimized.

Show comment
Hide comment
@whitlockjc

whitlockjc Jul 25, 2018

Member

Oh, I didn't take it that way. :) I wasn't pulling rank either but I can see how it could be taken that way.

Member

whitlockjc commented Jul 25, 2018

Oh, I didn't take it that way. :) I wasn't pulling rank either but I can see how it could be taken that way.

@whitlockjc

This comment has been minimized.

Show comment
Hide comment
@whitlockjc

whitlockjc Jul 25, 2018

Member

Speaking of...any ideas on how you'd like sway to work with multiple versions of OAS? As we support multiple concurrent versions of the spec, you get to the point where the size of sway will increase. Also, since these JSON Schemas are JSON they are not typically minified during browser builds. I'm thinking of creating JSON object versions of them to remedy this. Thoughts?

Member

whitlockjc commented Jul 25, 2018

Speaking of...any ideas on how you'd like sway to work with multiple versions of OAS? As we support multiple concurrent versions of the spec, you get to the point where the size of sway will increase. Also, since these JSON Schemas are JSON they are not typically minified during browser builds. I'm thinking of creating JSON object versions of them to remedy this. Thoughts?

@philsturgeon

This comment has been minimized.

Show comment
Hide comment
@philsturgeon

philsturgeon Jul 26, 2018

Many tools implement an adaptor pattern approach, where a base class covers the most basic common functionality and inheritence covers the rest. You'd probably have distinct v2 and v3 base classes, and v3.1 could extend from v3.0, etc.

Or you can use mixins to cherry-pick functionality from a whole bunch of things.

This JSON Schema library does something similar: https://github.com/davishmcclurg/json_schemer/tree/master/lib/json_schemer/schema

Also, with oas-kit covering a lot of the same functionality as you, but already supporting v3.0 rather well, I'd see if there was any functionality could combine. Even using their resolver and/or walker would help you delete some code. There are quite a few Node modules floating around now, and it would be great to see things combinging so we can all work on building awesome tooling on top of that base layer of components, instead of all competing to build this same components and being stuck on step 1. :)

philsturgeon commented Jul 26, 2018

Many tools implement an adaptor pattern approach, where a base class covers the most basic common functionality and inheritence covers the rest. You'd probably have distinct v2 and v3 base classes, and v3.1 could extend from v3.0, etc.

Or you can use mixins to cherry-pick functionality from a whole bunch of things.

This JSON Schema library does something similar: https://github.com/davishmcclurg/json_schemer/tree/master/lib/json_schemer/schema

Also, with oas-kit covering a lot of the same functionality as you, but already supporting v3.0 rather well, I'd see if there was any functionality could combine. Even using their resolver and/or walker would help you delete some code. There are quite a few Node modules floating around now, and it would be great to see things combinging so we can all work on building awesome tooling on top of that base layer of components, instead of all competing to build this same components and being stuck on step 1. :)

@whitlockjc

This comment has been minimized.

Show comment
Hide comment
@whitlockjc

whitlockjc Jul 26, 2018

Member

I'm all for collaboration. Being one of the first on the block for such things (sway started 2 years before oas-kit and was written to replace swagger-tools which was even older), I was surprised more people didn't contribute to my projects and would start their own. I've never pushed anyone away and I've been quite receptive to criticism and feedback. I'll stay in my lane for now and if people want to collaborate, I'd love to.

Member

whitlockjc commented Jul 26, 2018

I'm all for collaboration. Being one of the first on the block for such things (sway started 2 years before oas-kit and was written to replace swagger-tools which was even older), I was surprised more people didn't contribute to my projects and would start their own. I've never pushed anyone away and I've been quite receptive to criticism and feedback. I'll stay in my lane for now and if people want to collaborate, I'd love to.

@philsturgeon

This comment has been minimized.

Show comment
Hide comment
@philsturgeon

philsturgeon Jul 26, 2018

Excellent. Well, oas-kit is brand new but based on the logic from swagger2openapi, and of course exists because there are no v3.0-based tools out there. I wasn't suggesting ditching your thing because a new thing came along, but was suggesting you take a look at the multiple components they have to see if any of them can replace 2.0-only code you have there.

Another cool approach is to support v3.0 only, and use their swagger2openapi logic to convert in the background. That can really save some effort. :)

Either way, good luck with the v3.0-based tooling built on that WIP metaschema. I'm nudging the OpenAPI folks to get that finished up!

philsturgeon commented Jul 26, 2018

Excellent. Well, oas-kit is brand new but based on the logic from swagger2openapi, and of course exists because there are no v3.0-based tools out there. I wasn't suggesting ditching your thing because a new thing came along, but was suggesting you take a look at the multiple components they have to see if any of them can replace 2.0-only code you have there.

Another cool approach is to support v3.0 only, and use their swagger2openapi logic to convert in the background. That can really save some effort. :)

Either way, good luck with the v3.0-based tooling built on that WIP metaschema. I'm nudging the OpenAPI folks to get that finished up!

@whitlockjc

This comment has been minimized.

Show comment
Hide comment
@whitlockjc

whitlockjc Jul 26, 2018

Member

I do like that idea. I'll reach out to @MikeRalphson to see what his thoughts are.

Member

whitlockjc commented Jul 26, 2018

I do like that idea. I'll reach out to @MikeRalphson to see what his thoughts are.

@confuser

This comment has been minimized.

Show comment
Hide comment
@confuser

confuser commented Aug 13, 2018

@whitlockjc Probably worth taking a look at https://github.com/exegesis-js/exegesis as well

@DavidBiesack

This comment has been minimized.

Show comment
Hide comment
@DavidBiesack

DavidBiesack Sep 25, 2018

Glad to see progress and some momentum on 3.0. I would suggest, however, that the README.md not imply that master supports the latest (3.0) until it actually does.

DavidBiesack commented Sep 25, 2018

Glad to see progress and some momentum on 3.0. I would suggest, however, that the README.md not imply that master supports the latest (3.0) until it actually does.

@rahimimo

This comment has been minimized.

Show comment
Hide comment
@rahimimo

rahimimo Sep 26, 2018

I agree with @DavidBiesack I really do not know if now 3 is fully supported or not and what is the correct source to follow,. This issue thread or readme or ?

rahimimo commented Sep 26, 2018

I agree with @DavidBiesack I really do not know if now 3 is fully supported or not and what is the correct source to follow,. This issue thread or readme or ?

@whitlockjc

This comment has been minimized.

Show comment
Hide comment
@whitlockjc

whitlockjc Sep 26, 2018

Member

Can I say that master supports v3.x (WIP)?

Member

whitlockjc commented Sep 26, 2018

Can I say that master supports v3.x (WIP)?

@DavidBiesack

This comment has been minimized.

Show comment
Hide comment
@DavidBiesack

DavidBiesack Sep 28, 2018

I suggest not claiming that master supports v3 as a work in progress.
I recommend creating a separate branch for the 3.0 work.
At APIStrat, Jeremy asked about approaches for 3.0 support - I'd like to see sway support both "swagger: 2.0" and "openapi: 3.0.1" at the same time (same code base), rather that forking the tool. That's my opinion, tho.
I don't recommend doing so via an implicit conversion (ala api-spec-converter or other), since error messages would become perturbed, perhaps pointing to paths such as /components/schemas (that do not appear in the 2.0 source) instead of /definitions

DavidBiesack commented Sep 28, 2018

I suggest not claiming that master supports v3 as a work in progress.
I recommend creating a separate branch for the 3.0 work.
At APIStrat, Jeremy asked about approaches for 3.0 support - I'd like to see sway support both "swagger: 2.0" and "openapi: 3.0.1" at the same time (same code base), rather that forking the tool. That's my opinion, tho.
I don't recommend doing so via an implicit conversion (ala api-spec-converter or other), since error messages would become perturbed, perhaps pointing to paths such as /components/schemas (that do not appear in the 2.0 source) instead of /definitions

@whitlockjc

This comment has been minimized.

Show comment
Hide comment
@whitlockjc

whitlockjc Sep 28, 2018

Member

I fixed the supported version in the README files. And thanks for the feedback. I like that approach too.

Member

whitlockjc commented Sep 28, 2018

I fixed the supported version in the README files. And thanks for the feedback. I like that approach too.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment